/****************************************************************************
**
** 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.
**
****************************************************************************/

/*!
    \previouspage qtquick-adding-dynamics.html
    \page studio-timeline.html
    \nextpage qmldesigner-connections.html

    \title Creating Animations

    Animation is based on \e keyframes. In \QC, keyframes determine the value
    of the property of a \l{glossary_component}{component} at a certain time.
    Animating properties enables their values to move through intermediate
    values instead of immediately changing to the target value.

    For example, you can set the y position property of a rectangle to 0 at the
    start of your animation and to 100 at the end of the animation. When the
    animation is run, the rectangle moves from position 0 to 100 on the y axis.
    In the middle of the animation, the y property has the value of 50 since
    keyframes are interpolated linearly by default.

    Sometimes you don't want linear movement but would rather like the rectangle
    to move faster at the beginning and slower at the end of the animation.
    To achieve this effect, you could insert a lot of keyframes between the
    start frame and the end frame. To avoid this effort, you can use the
    \l{Editing Easing Curves}{Easing Curve Editor} to specify \e {easing curves}
    for nonlinear interpolation between keyframes. The easing curves can make
    components appear to pick up speed, slow down, or bounce back at the end of
    the animation.

    While easing curves work well for most simple UI animations, more complex
    3D animations require several keyframes so it becomes necessary to visualize
    the value and the interpolation of a keyframe simultaneously. The
    \l {Curve Editor} visualizes the whole animation of a property at once and
    shows the effective values of a keyframe together with the interpolation
    between keyframes. It can also show animations of different properties
    simultaneously so that you can see the animation for the x position
    side-by-side with the animation of the y position.

    You can declare various UI states as \l{Adding States}{states}, which
    are specified as changes from a base state and can be a useful way of
    organizing your UI logic. You can \l{Binding Animations to States}
    {bind animations to states} to run an animation when a state is applied.

    Each component in a scene or a project can have its own timeline and its own
    set of states. We recommend that you place your timelines inside the
    components and precompose them. Each component's timeline runs independently
    of the rest of the scene, allowing for time-independent animations.
    Additionally, separate states allow common functionality to be factored out
    and reused across the scene. Do note, however, that adding states and
    timelines to your components will increase the file size and runtime memory
    requirements of your UI.

    The following video shows how to animate component properties using the
    timeline and keyframe based editor in the \l Timeline view:

    \youtube V3Po15bNErw

    \if defined(qtcreator)
    To be able to create timelines, you also need the \l {Qt Quick Timeline}
    add-on module, which you can install with Qt 5.14, and later. For more
    information about adding the module to an older Qt version, see
    \l{Adding Qt Quick Timeline Module to Qt Installations}.
    \endif

    \section1 Creating Timelines

    You specify settings for the timeline and for running the animation in the
    \uicontrol {Timeline Settings} dialog. The \uicontrol Animation radio button
    is selected for a timeline animation and the \uicontrol {Expression binding}
    radio button for a \l{Setting Bindings}{property animation}.

    \image studio-timeline-settings.png "Timeline Settings dialog"

    To create a timeline to animate a UI component:

    \list 1
        \li In the \l Timeline view, select the \inlineimage plus.png
            (\uicontrol {Add Timeline}) button to specify settings
            for the timeline and running the animation
            in the \uicontrol {Timeline Settings} dialog.
        \li In the \uicontrol {Timeline ID} field, enter an ID that describes
            the animated component.
        \li In the \uicontrol {Start frame} field, set the first frame of the
            timeline. Negative values are allowed.
        \li In the \uicontrol {End frame} field, set the last frame of the
            timeline.
        \li In the \uicontrol {Animation ID} field, enter an ID for the
            animation.
        \li Select the \uicontrol {Running in Base State} check box to run the
            animation when the base state is applied. Deselect the check box
            if you want to run the animation when some other state is applied.
            For more information, see \l{Binding Animations to States}.
        \li In the \uicontrol {Start frame} field, set the first frame of the
            animation.
        \li In the \uicontrol {End frame} field, set the last frame of the
            animation.
        \li In the \uicontrol {Duration} field, set the length of the
            animation from the start frame to the end frame. If you set a
            shorter duration than the number of frames, frames are left out
            from the end of the animation when viewing it.
        \li Select the \uicontrol Continuous check box to loop the animation
            indefinitely.
        \li In the \uicontrol Loops field, select the number of times to run
            the animation as a loop. The default number of loops is one, which
            means that you must restart the animation to see it again
        \li Select the \uicontrol {Ping pong} check box to play the animation
            backwards back to the beginning when it reaches the end.
        \li In the \uicontrol Finished field, select the state
            to apply when the animation finishes.
        \li Select \uicontrol Close to close the dialog and save the settings.
    \endlist

    To create additional timelines, select the \inlineimage plus.png
    (\uicontrol {Add Timeline}) button next to the
    \uicontrol {Timeline Settings} tab.

    To specify settings for running timeline animations, select the
    \inlineimage plus.png
    (\uicontrol {Add Animation}) button next to the
    \uicontrol {Animation Settings} tab. For example, you could create
    settings for running a part of the timeline animation between specified
    frames or for running the animation backwards from the last frame to the
    first.

    To modify the settings, select the \inlineimage animation.png
    (\uicontrol {Timeline Settings (S)}) button on the \l{Timeline Toolbar}
    {toolbar} (or press \key S) in the \l Timeline view.

    \section2 Binding Animations to States

    The table at the bottom of the \uicontrol {Timeline Settings} dialog lists
    the available states. Double-click the values in the \uicontrol Timeline
    and \uicontrol Animation column to bind the states to animations. In the
    \uicontrol {Fixed Frame} column, you can bind the states that don't have
    animations to fixed frames.

    \section1 Managing Keyframes

    To animate components in the \l Timeline view, move to a frame
    on the timeline and specify changes in the values of a property. \QC
    automatically adds keyframes between two keyframes and sets their values
    evenly to create an appearance of movement or transformation.

    \image studio-timeline-with-tracks.png "Timeline view"

    \section2 Setting Keyframe Values

    You can insert keyframes for all the properties of all the components that
    you want to animate first, and then record the changes in their values by
    selecting the \inlineimage local_record_keyframes.png
    (\uicontrol {Per Property Recording}) button for one property at a time.
    For example, you can hide and show components by turning their visibility
    off and on or by setting their opacity to 0 or 1.

    You can also select the \uicontrol {Auto Key (K)} button (or press \key K)
    to record changes in property values, but you need to be more careful about
    which property values you are changing to avoid surprises.

    To record the changes of property values:

    \list 1
        \li In the \l Navigator view, select the component to animate.
        \li In the \l Properties view, select \uicontrol Settings >
            \uicontrol {Insert Keyframe} for the property that you want to
            animate.
        \li In the \l Timeline view, select the
            \uicontrol {Per Property Recording} button
            to start recording property changes.
        \li Check that the playhead is in frame 0 and enter the value of the
            property in the field next to the property name on the timeline.
            Press \key Enter to save the value.
        \li Move the playhead to another frame on the timeline and specify
            the value at that frame. For more information, see
            \l{Navigating in Timeline}.
        \li When you have specified as many values as you need, select
            \uicontrol {Per Property Recording} again to stop recording.
    \endlist

    To remove all the changes you recorded for a property, right-click the
    property name on the timeline and select \uicontrol {Remove Property}.

    To add keyframes to the keyframe track of a component at the current
    position of the playhead, select \uicontrol {Add Keyframes at Current Frame}.

    Keyframes are marked on the timeline by using \l{keyframe_marker}{markers}
    of different colors and shapes, depending on whether they are active or
    inactive or whether you have applied \l{Editing Easing Curves}
    {easing curves} to them.

    \section2 Editing Keyframe Values

    To fine-tune the value of a keyframe, double-click a keyframe marker or
    select \uicontrol {Edit Keyframe} in the context menu.

    The \uicontrol {Edit Keyframe} dialog displays the name of the property
    you are animating and its current value at the frame specified in the
    \uicontrol Frame field. You can change both the keyframe and its value.

    \image studio-edit-keyframe.png "Edit Keyframe dialog"

    \section2 Copying Keyframes

    You can copy the keyframes from the keyframe track for a component and
    paste them to the keyframe track of another component. To copy all
    keyframes from one track to another one, first right-click the component ID
    and select \uicontrol {Copy All Keyframes} in the context menu.
    Then right-click the other component ID, and select
    \uicontrol {Paste Keyframes} in the context menu.

    \section2 Deleting Keyframes

    To delete the selected keyframe, select \uicontrol {Delete Keyframe} in the
    context menu.

    To delete all keyframes from the selected component, select
    \uicontrol {Delete All Keyframes} in the context menu.

    \section1 Viewing the Animation

    You can view the animation on the canvas by moving the playhead along the
    timeline.

    To preview the animation, select the \uicontrol {Play (Space)}
    button or press \key Space. To preview the whole UI, select the
    \inlineimage live_preview.png
    (\uicontrol {Show Live Preview}) button on the canvas toolbar
    or press \key {Alt+P}.

    \section1 Animating Rotation

    To animate components that rotate around a central point, you can use the
    \l {basic-item}{Item} component as a parent for the rotating component. Then
    create a timeline for the Item, and set the rotation property for the start
    and end keyframes.

    \if defined(qtdesignstudio)
    \section1 Animating Shapes

    You can use the \uicontrol {Qt Quick Studio Components} to animate the
    following shapes:

    \list
        \li \l Arc
        \li \l Border
        \li \l Pie
        \li \l Rectangle
        \li \l Triangle
    \endlist
    \endif
*/
