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

/*!
    \example Loginui4
    \ingroup gstutorials

    \title Login UI: Timeline
    \brief Illustrates how to use the timeline and states to animate UI
    components.
    \previouspage {Login UI: States}

    \image loginui4.gif "Login UI"

    \e{Login UI: Timeline} 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. The
    fourth part of the tutorial describes how to use the timeline and states
    to animate UI components. The result of this final tutorial is a UI similar
    to the preceding animation, where you can navigate to the account creation
    page by clicking the \e {Create Account} button.

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

    The starting point for this tutorial is the completed
    \l{Login UI: States} project. You can download the project
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui3}{here}.

    Additionally, you can download the completed project of this tutorial
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui4}{here}.

    For more information, see \l {Creating timeline animations}.

    \section1 Animating UI components

    In \l {Login UI: States}, 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 next, you
    will first remove the states.

    Then, you will add a timeline and insert keyframes for the opacity property
    to hide the \e {Repeat Password} field on the login page and the
    \e {Create Account} button on the account creation page. Because we want the
    \e {Repeat Password} field to appear to slide down from the \e 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
    column component and anchor them to the rectangle and to each other instead.

    To preview the changes that you make, select the \uicontrol {Live Preview} button
    or select \key {Alt+P}.

    \section2 Replacing columns with anchors

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

    \list 1
        \li Double-click \e Screen01.ui.qml in \l Projects to open it
            in the \l {2D} view.
        \li In the \l States view, select \e login > \imagemorebutton
            > \uicontrol Delete to remove the state. Repeat for the \e createAccount state.
        \li Select \e username in \l Navigator, and then select:
            \list
                \li \imagearrowleft to move \e username into the parent
                    rectangle.
                \li \imagenavigatorarrowup to move \e username below
                    \e tagLine in \uicontrol Navigator to preserve the
                    \l{Arranging components}{component hierarchy}.
            \endlist
        \li Repeat the previous step for \e password and \e repeatPassword.
        \li Select \e fields in \uicontrol Navigator and select \key Delete to
            delete it.
            \image loginui4-hierarchy.webp "The hierarchy of the components."
        \li Select \e username in \uicontrol Navigator.
        \li In \uicontrol Properties > \uicontrol Layout, set:
            \list
                \li \uicontrol Anchors to \imageanchortop and
                    \imageanchorcenterhorizontal.
                \li \uicontrol Target \imageanchortop to
                    \e tagLine to anchor \e username to the tag line.
                \li \uicontrol Margin \imageanchortop to \e 170 and
                    select \imageanchorbottom to anchor \e username to the
                    bottom of the target.
                    \note Selecting the anchor button should automatically update the
                    \uicontrol {2D} view. If it doesn't, select \imagereset
                    on the \uicontrol {2D} view toolbar to refresh the \uicontrol{2D} view.
            \endlist
            This attaches \e username to the bottom of the tag line while keeping its
            horizontal center aligned with that of the rectangle.
            \image loginui4-username-layout.webp "The layout of username entry field."
        \li Select \e password in \uicontrol Navigator.
        \li In \uicontrol Properties > \uicontrol Layout, set:
            \list
                \li \uicontrol Anchors to \imageanchortop and
                    \imageanchorcenterhorizontal.
                \li \uicontrol Target \imageanchortop to
                    \e username to anchor \e password to \e username.
                \li \uicontrol Margin \imageanchortop to \e 20 and
                    select \imageanchorbottom to anchor \e password to the
                    bottom of the target.
            \endlist
            This attaches \e password to the bottom of \e username while keeping its
            horizontal center aligned with that of the rectangle.
            \image loginui4-password-layout.webp "The layout of password entry field."
        \li Repeat the previous step to anchor the top of \e repeatPassword
            to the bottom of \e password with a margin of \e 20 and to
            anchor it horizontally to its parent.
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    \e Screen01 should not display visible changes in the \uicontrol {2D} view:

    \image loginui4-base-state.webp "UI with all the buttons and fields"

    \section2 Adding a timeline

    You are now ready to add the \l{Creating timeline animations}{timeline}.

    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 \imageplus
            to add a 1000-frame timeline and define settings for running the animation.
        \li In the \uicontrol {Animation ID} field, enter
            \e toCreateAccountState.
        \li Clear the \uicontrol {Running in base state} checkbox because
            you want the animation to run only after the user clicks the
            \e {Create Account} button. Use the default settings
            for the other fields.
        \li Select \uicontrol Close in the \uicontrol {Timeline Settings} view
            to save the timeline and the animation settings.
            \image loginui4-timeline-settings.png
    \endlist

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

    \section2 Inserting keyframes

    To insert keyframes and record property changes in \uicontrol Timeline:

    \list 1
        \li Select \e repeatPassword in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol Visibility > \uicontrol Opacity, select
            \imageactionicon
            > \uicontrol {Insert Keyframe} to insert a keyframe for the
            opacity property of the component.
            \image loginui4-keyframe-opacity.png "Inserting keyframe for opacity property"
        \li In \uicontrol Timeline, check that the playhead is in
            frame \e 0, select the small arrow next to \e repeatPassword
            keyframe to expand it, and then select the \imagerecordfill
            (\uicontrol {Per Property Recording}) button for the
            \uicontrol opacity property of \e repeatPassword to start
            recording property changes.
        \li In \uicontrol Visibility > \uicontrol Opacity, enter \e 0 to hide the button, and press
            \key Enter to save the value.
        \li Move the playhead to frame \e 1000 and change the opacity value to \e 1
            to show the button.

            Alternatively, you can fine-tune the value of a keyframe by right-clicking the
            keyframe marker \imagekeyframelinearactive
            , and selecting \uicontrol {Edit Keyframe}.
            \image loginui4-timeline.webp "Recording the opacity property"
        \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 createAccount 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 \e 1 in frame \e 0 and \e 0 in frame \e 1000.
            \image loginui4-timeline-opacity.webp "Recorded timeline for the opacity properties"
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    When you move the playhead along the timeline, you can see how the \e {Create Account}
    button fades out while the \e {Repeat Password} field fades in.

    You will now animate the top anchor margin of the \e {Repeat Password} field
    to make it appear to slide down from the \e Password field.

    \section2 Animating anchors

    To animate the top anchor margin of the \e {Repeat Password} field:

    \list 1
        \li Select \e repeatPassword in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol Layout > \uicontrol Margin (under
            \imageanchortop
            ), select \imageactionicon
            > \uicontrol {Insert Keyframe} to insert a keyframe for the top
            anchor margin of \e repeatPassword.
            \image loginui4-keyframe-top-anchor-margin.png "Inserting keyframe for top anchor margin"
        \li In \uicontrol Timeline, check that the playhead is in
            frame \e 0, and select the record button for the \e anchors.topMargin
            property of \e repeatPassword.
        \li In \uicontrol Layout > \uicontrol Margin (under \imageanchortop),
            set a negative value for the top anchor margin, \e -100, to place \e repeatPassword
            on top of \e password.
        \li Move the playhead to frame \e 1000 and change the top anchor margin
            to \e 20, so that, combined with the change in the \uicontrol Opacity
            value, \e repeatPassword appears to slide down and settle below
            \e password.
        \li Select the record button again to stop recording property changes.
        \image loginui4-timeline-all.webp "Recorded timeline for repeatPassword and createAccount."
        \li Select \uicontrol File > \uicontrol Save or select \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 \imagekeyframelinearactive
            for the \e anchors.topMargin property at frame \e 1000 on the
            timeline to select it.
            \image loginui4-easing-curve-top-anchor-margin.webp "Top anchor margin keyframe marker"
        \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 \imagekeyframelinearactive
    to \imagekeyframemanualbezieractive
    .

    Your timeline should now look something like this:

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

    Next, you will create states for the login and account creation pages and bind
    them to the animation settings.

    \section1 Binding animation to states

    To bring back the \l{Working with states}{states} in the
    \uicontrol States view and bind them to the animation settings
    in \uicontrol Timeline:

    \list 1
        \li In \uicontrol States, select \imageplus
            twice to add two states and name them \e login and \e createAccount. You
            don't need to make any property changes this time because you'll
            bind the states to property animations.
        \li In \uicontrol States, select \uicontrol Default for \e login to determine that
            the \e login state is applied when the application starts.
            \image loginui4-states.webp "Created states in the States view."
        \li With the base state selected, select \uicontrol Timeline >
            \imagesettings (\uicontrol {Timeline Settings (S)}) on the toolbar
            (or select \key S) to open the \uicontrol {Timeline Settings} dialog.
        \li Double-click the cell in the \uicontrol Timeline column on the
            \e login row, and select \e timeline in the list.
        \li Double-click the cell in the \uicontrol Timeline column on the
            \e createAccount row, and select \e timeline in the list.
        \li Double-click the cell in the \uicontrol Animation column on the
            \e createAccount row, and select \e toCreateAccountState.
            \image loginui4-timeline-settings-states.png
        \li Click \uicontrol Close to save the timeline settings.
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    In the live preview, you can now click the \e {Create Account}
    button to go to the account creation page.

    \image loginui4.gif "Moving between login page and account creation page"

    \section1 Next steps

    To continue learning about \QDS, see \l{Examples} and other \l{Tutorials}.
*/
