/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Design Studio 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.
**
****************************************************************************/

/*!
    \example loginui4
    \ingroup studioexamples
    \ingroup gstutorials

    \title Log In UI - Part 4
    \brief Illustrates how to use the timeline and states to animate UI
    components.
    \previouspage {Log In UI - Part 3}

    \image loginui4.gif "Log In UI"

    \e{Log In UI - Part 4} is the fourth in a series of tutorials that build
    on each other to illustrate how to use \QDS to create a simple UI with
    some basic UI components, such as pages, buttons, and entry fields. Part 4
    describes how to use the timeline and states to animate UI components.

    In Part 3, you learned how to use states to simulate page changes in a UI
    and connections to provide user interaction with it. In Part 4, you will now
    learn another way of animating the UI by creating \l{Creating Animations}
    {timeline animations} that you bind to states.

    These instructions build on:

    \list
        \li \l {Log In UI - Part 1}
        \li \l {Log In UI - Part 2}
        \li \l {Log In UI - Part 3}
    \endlist

    The \e {Learn More} sections provide additional information relevant to the
    task at hand.

    \section1 Animating UI Components

    In Part 3, you changed the visibility property in different states to
    simulate changing pages. To make sure that those changes won't interfere
    with the changes to the opacity property you will make in Part 4, you will
    first remove the states.

    Then, you will add a timeline and insert keyframes for the opacity property
    to hide the password verification field and back button on the login page
    and the login button on the registration page. Because we want the password
    verification field to appear to slide down from the password field, you will
    also need to insert a keyframe for its anchor margin property. To be able to
    animate the anchor, you also need to pull out the fields from the fields
    column and anchor them to the page and to each other instead.

    To preview the changes that you make to the UI while you make
    them, select the \inlineimage live_preview.png
    (\uicontrol {Show Live Preview}) button on the \uicontrol Design
    mode \l {Summary of Main Toolbar Actions}{toolbar} or press \key {Alt+P}.

    \section2 Replacing Columns with Anchors

    First, you will prepare the \e Screen01 component for adding animation:

    \list 1
        \li Open \e {Screen01.ui.qml} in \l {Form Editor} for editing.
        \li In the \l States view, select the \inlineimage close.png
            (\uicontrol Close) button in \e loginState and \e registerState
            to remove the states.
        \li Select the fields in \e fieldColumn in \l Navigator
            and drag and drop them to their parent rectangle to prepare for
            deleting the column component.
        \li Select \e fieldColumn in \uicontrol Navigator and press
            \key Delete to delete it.
        \li Select \e usernameField in \uicontrol Navigator.
        \li In \l Properties > \uicontrol Layout, select the
            \inlineimage icons/anchor-top.png
            (\uicontrol Top) button to anchor the top of the field to the top
            of its parent. \QDS will suggest an appropriate margin based on
            the current position of the field on the y axis, 200 pixels.
        \li Select the \inlineimage icons/anchor-center-horizontal.png
            (\uicontrol {Horizontal Center}) button to anchor
            the horizontal center of the field to that of its parent.
        \li Select \e passwordField, and then select the \uicontrol Top
            button in \uicontrol Properties > \uicontrol Layout.
        \li In the \uicontrol Target field, select \e usernameField to anchor
            the top of \e passwordField to the bottom of \e usernameField
            with a 5-pixel margin.
        \li Select the \uicontrol {Horizontal Center} button to anchor the
            horizontal center of \e passwordField to that of \e usernameField.
        \li Repeat the above steps to anchor the top of \e verifyPasswordField
            to the bottom of \e passwordField with a 5-pixel margin and to
            anchor its horizontal center to that of \e passwordField.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    You could also animate the y-position property of the verify password
    field for a similar effect. In that case, you would need to use absolute
    positioning for the field. This is less flexible if you export your
    design from a design tool, such as Adobe Photoshop, and decide to change
    your design and export it again at some point. In that case, the margins
    would probably stay the same, even if the positions of the fields on the
    page would change.

    \e Screen01 should now look something like this in the \uicontrol Design
    mode and live preview:

    \image loginui4-page.png "UI with all the buttons and fields in the Design mode"

    \section2 Adding a Timeline and Animation Settings

    You are now ready to add the \l{Creating Animations}{timeline}. You will
    need two animations, one for moving into the registration page and another
    for returning to the login page. You can use the same animation for both
    cases, by running it either from the beginning to the end or from the
    end to the beginning.

    To add a timeline with settings for running the animation:

    \list 1
            \li Select \uicontrol View > \uicontrol Views >
            \uicontrol Timeline to open the \l Timeline view.
        \li In \uicontrol Timeline, select \inlineimage plus.png
            to add a 1000-frame timeline and settings for running the animation.
            \image loginui4-timeline-settings.png
        \li In the \uicontrol {Animation ID} field, enter \e toLoginState.
        \li Deselect the \uicontrol {Running in base state} check box, because
            you want the animation to run only after the user clicks the
            \uicontrol {Create Account} button. You can use the default settings
            for the other fields.
        \li Select \inlineimage plus.png
            next to the \uicontrol {Animation Settings} group to add settings
            for running the animation when the user clicks the back button.
        \li In the \uicontrol {Animation ID} field, enter \e toRegisterState.
        \li To run the animation backwards when the user clicks the back button,
            enter \e 1000 in the \uicontrol {Start frame} field and \e 0 in the
            \uicontrol {End frame} field.
        \li Select \uicontrol Close in the \uicontrol {Timeline Settings} view
            to save the timeline and the animation settings.
    \endlist

    Next, you will record the animation in \uicontrol Timeline.

    \section2 Inserting Keyframes

    You will now insert keyframes and record property changes in
    \uicontrol Timeline:

    \list 1
        \li Select \e backButton in \uicontrol Navigator.
        \li In \uicontrol Properties > \uicontrol Opacity > \uicontrol Settings,
            select \uicontrol {Insert Keyframe} to insert a keyframe for the
            opacity property of the button.
        \li In \uicontrol Timeline, check that the playhead is in
            frame 0, and select the \inlineimage recordfill.png
            (\uicontrol {Per Property Recording}) button for the
            \uicontrol opacity property of \e backButton to start
            recording property changes.
            \image loginui4-timeline-opacity.png "Record button for the opacity property"
        \li In the field next to the opacity property name on that same line,
            type 0 to hide the button, and press \key Enter to save the value.
        \li Move the playhead to frame 1000 and change the opacity value to 1
            to show the button.

            To fine-tune the value of a keyframe, you can also right-click the
            keyframe marker \inlineimage keyframe_linear_inactive.png
            , and select \uicontrol {Edit Keyframe}.
        \li Select the record button again to stop recording property changes.
            If you forget this, all the following changes will be recorded, and
            the results will be unpredictable.
        \li Select \e verifyPasswordField in \uicontrol Navigator,
            and repeat the above steps to insert a keyframe for the
            \uicontrol opacity property of the field and to record
            changes for it.
        \li Select \e loginButton in \uicontrol Navigator, and repeat
            the above steps to insert a keyframe for the \uicontrol opacity
            property of the button and to record changes for it. However, this
            time the opacity value needs to be 1 in frame 0 and 0 in frame 1000.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    When you move the playhead along the timeline, you can see how the login
    button fades out while the verify password field and back button fade in.

    You will now animate the top anchor margin of the verify password field
    to make it appear to slide down from the password field.

    \section2 Animating Anchors

    To animate the top anchor margin of the verify password field:

    \list 1
        \li Select \e verifyPasswordField in \uicontrol Navigator.
        \li Select \uicontrol Properties > \uicontrol Layout > \uicontrol Margin
            > \uicontrol {Insert Keyframe} to insert a keyframe for the top
            anchor margin of \e verifyPasswordField.
        \li In \uicontrol Timeline, check that the playhead is in
            frame 0, and select the record button for the \e anchors.topMargin
            property of \e verifyPasswordField.
        \li In the field next to the property, set a negative value for the
            top anchor margin, -40, to place \e verifyPasswordField on top of
            \e passwordField.
        \li Move the playhead to frame 1000 and change the top anchor margin
            to 5, so that, combined with the change in the opacity value,
            \e verifyPasswordField appears to slide down and settle below
            \e passwordField.
        \li Select the record button again to stop recording property changes.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    \section2 Adding Easing Curves

    You will now add an \l{Editing Easing Curves}{easing curve} to the anchor
    margin animation that will make the transition seem smoother:

    \list 1
        \li Click the keyframe marker \inlineimage keyframe_linear_inactive.png
            for the \e anchors.topMargin property at frame 1000 on the
            timeline to select it.
        \li Right-click the keyframe marker to open a context menu, and
            select \uicontrol {Edit Easing Curve} to add an easing curve
            to the animation.
        \li In \uicontrol {Easing Curve Editor}, select \e easeOutSine.
            \image loginui4-easing-curve.png
        \li Select \uicontrol OK to close the editor.
    \endlist

    When you attach easing curves to keyframes, the shape of the keyframe
    marker changes from \inlineimage keyframe_linear_inactive.png
    to \inlineimage keyframe_manualbezier_inactive.png
    .

    Your timeline should now look something like this:

    \image loginui4-timeline.png "Timeline view with the recorded property changes"

    Next, you'll create states for the login and registration pages and bind
    them to the animation settings.

    \section1 Binding Animation to States

    You will now bring back the \l{Adding States}{states} in the
    \uicontrol States view and bind them to the animation settings
    in \uicontrol Timeline:

    \list 1
        \li In \uicontrol States, select \uicontrol {Create New State} twice to
            add two states called \e loginState and \e registerState. You don't
            need to make any property changes this time, because you'll bind the
            states to property animations.
        \li In \uicontrol Timeline, select the \inlineimage animation.png
            (\uicontrol {Timeline Settings (S)}) button on the toolbar (or press
            \key S to open the \uicontrol {Timeline Settings} dialog.
            \image loginui4-timeline-settings-states.png
        \li Double-click the cell in the \uicontrol Timeline column on the
            \e loginState row, and select \e timeline in the list.
        \li Double-click the cell in the \uicontrol Animation column on the
            \e loginState row, and select \e toRegisterState.
        \li Repeat these steps for \e registerState row, but select
            \e toLoginState in the \uicontrol Animation column.
        \li Click \uicontrol Close to save the timeline settings.
    \endlist

    In the live preview, you can now click the \uicontrol {Create Account}
    button to go to the registration page and the back button to return to
    the login page.

    \image loginui4.gif "Moving between login page and registration page"

    \section2 Learn More - Timeline

    The Qt Quick Timeline module provides components to use timelines and
    keyframes to animate component properties in UIs. Animating properties
    enables their values to move through intermediate values instead of
    immediately changing to the target value.

    The Keyframe component specifies the value of a keyframe on a timeline. \QDS
    automatically adds keyframes between two keyframes, and sets their values
    evenly to create an appearance of movement or transformation.

    An easing curve can be attached to the keyframe to change the appearance
    of the animation. For more information about easing curve types, see the
    documentation for \l [QML] {PropertyAnimation}{easing curves}.

    To be able to use the functionality of Timeline components, \QDS adds
    the following \e import statement to the UI files where it uses the
    components:

    \quotefromfile loginui4/Screen01.ui.qml
    \skipto QtQuick.Timeline
    \printuntil 1.0

    All the properties and functions of the components from this module are
    available in the \uicontrol Design mode, and therefore it is enough to
    learn how to use \uicontrol Timeline, as described in
    \l {Creating Animations}.

    \section1 Next Steps

    For more examples about using timelines, see \l{Examples and Tutorials}.

    Watch a video tutorial about creating timelines and adding keyframes:

    \youtube Z3uPoe-4UAw
*/
