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

/*!
    \page quick-animations.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-design-qtquick-animation

    \title Animate property changes

    To create an animation, use the appropriate animation type for the property
    that is to be animated, and apply the animation depending on the type of
    behavior that is required.

    You can drag animation components from \uicontrol Components >
    \uicontrol {Default Components} > \uicontrol Animation to the
    \uicontrol {Navigator} or \uicontrol {2D} view to
    create instances of them.

    You can achieve similar results by using different animation techniques.
    For more information, see \l{Adding animation}.

    \section1 Apply animations

    A property animation is applied when the value of a property changes.
    Color and number animations are property animation types for specific
    purposes. Specify settings for animations in \uicontrol {Properties} >
    \uicontrol {Animation Targets}.

    \section2 Animate color changes

    For example, you can apply animation to the value of the \uicontrol Color
    property of an instance of a \l Rectangle component to change its value
    from its current color to another color over a period of time specified in
    milliseconds.

    \image {qtquick-color-animation.gif} {A color animation.}

    \list 1
        \li Create an instance of the \uicontrol {Color Animation} component in
            the \uicontrol 2D view.
        \li Go to \uicontrol {Properties} > \uicontrol {Animation Targets}.
        \li In \uicontrol Target, select the component to animate.
        \li In \uicontrol Property, enter the property to animate. To animate
            several properties, separate them by commas.
            \image {qtquick-properties-coloranimation.png} {Color Animation properties.}
        \li In the \uicontrol {Color Animation} section, select the original
            color in \uicontrol {From color} and the new color in
            \uicontrol {To color}.
        \li In the \uicontrol {Animation} section, set the duration of the
            animation in \uicontrol Duration.
    \endlist

    \section2 Animate changes in numerical values

    Similarly, to apply animation when a numerical value of a property changes,
    create an instance of the \uicontrol {Number Animation} component.

    \list 1
        \li Go to \uicontrol {Properties} > \uicontrol {Number Animation}.
            \image {qtquick-properties-numberanimation.png} {Number Animation properties.}
        \li Select the original value in \uicontrol From and the new value in
            \uicontrol To.
        \li In the \uicontrol {Animation} section, set the duration of the
            animation in \uicontrol Duration.
    \endlist

    For example, you can apply animation to the value of the \uicontrol X
    property of a \l Rectangle instance to make it appear to move from its
    current position on the x axis to another position over a period of time
    specified in milliseconds. To make the component appear to move both on
    the x and y axis, enter x and y into the \uicontrol Properties field
    separated by a comma.

    \image {qtquick-number-animation.gif} {Number animation.}

    For an example of using property animation to animate the scale and opacity
    of components, see the \l{Coffee Machine} example.

    \section2 Set non-animated properties

    To immediately change a property value during an animation
    without animating the property change:

    \list 1
        \li Create an instance of the \uicontrol {Property Action} component in
            the \uicontrol Navigator.
        \li Go to \uicontrol Properties > \uicontrol {Property Action}
            \image {qtquick-properties-propertyaction.png} {Property Action properties.}
        \li Set the value in the \uicontrol Value field.
    \endlist

    This is useful for setting non-animated property values during an animation.

    For example, you can create an instance of the
    \uicontrol {Sequential Animation} component that contains two instances
    of the \uicontrol {Property Action} component around an instance of the
    \uicontrol {Number Animation} component. The first property action sets
    the \uicontrol Opacity property of a \l{Rectangle} to \c 0.5, the number
    animation changes the width of the image, and the second property action
    sets the opacity back to \c 1.

    \image {qtquick-property-action.gif} {Sequential property actions and number animation.}

    \section1 Play animations

    To specify settings for playing animations, go to \uicontrol Properties >
    \uicontrol Animation.

    \image {qtquick-properties-animation.png} {Animation properties.}

    To run animations automatically, select \uicontrol Running.
    Animations are run for the time you specify in the
    \uicontrol Duration field.

    You can connect the running property of an animation to a signal emitted
    by a component to play the animation when users select a button, for
    example. For more information, see \l{Connect components to signals}.

    To run animations several times in a loop, set the number of times they
    should play in the \uicontrol Loops field. Set the value to -1 to have
    the animation continuously repeat until it is explicitly stopped.

    To specify that animations should run to completion when they are stopped,
    select \uicontrol {Run to end}. This behavior is most useful
    when the \uicontrol Loops property is set, as the animation will finish
    playing normally but not restart.

    All animations defined for a component are run in parallel,
    unless you include them in a \uicontrol {Parallel Animation} or
    \uicontrol {Sequential Animation} component for managing them as a
    group.

    To pause animations, select \imagepauseicon
    (\uicontrol Paused).

    To attach an \l{Edit easing curves}{easing curve} to
    the animation, select the \imagecurveeditor
    (\uicontrol {Easing Curve Editor}) button in the
    \uicontrol {Easing Curve} field.

    \section2 Play groups of animations

    You can create several animations that can run in parallel or in sequence.

    To manage a group of animations that will play at the same time:

    \list 1
        \li Create an instance of a \uicontrol {Parallel Animation} component
            in the \uicontrol Navigator.
        \li Drag the other animations to it.
    \endlist

    To play the animations in the specified order, one after the other, create an
    instance of a \uicontrol {Sequential Animation} instead.

    For example, a banner component may have several icons or slogans to
    display, one after the other. The value of the \uicontrol Opacity property
    could change to \c 1.0 denoting an opaque object. Using a sequential
    animation, each opacity animation will play after the preceding animation
    finishes, whereas using a parallel animation will play the animations at
    the same time.

    If you place individual animations into a group of parallel or sequential
    animations, you can no longer start or stop them independently. You must
    start and stop them as a group.

    \section3 Add pauses between grouped animations

    When used in a \uicontrol {Sequential Animation}, a
    \uicontrol {Pause Animation} is a step when nothing happens, for a specified
    duration.

    To specify a pause between two animations:

    \list 1
        \li Create an instance of the \uicontrol {Pause Animation} component
            within a \uicontrol {Sequential Animation} in the
            \uicontrol Navigator.
        \li Go to \uicontrol Properties > \uicontrol Animation.
        \li Select \uicontrol Paused.
        \li Set the duration of the pause in the \uicontrol Duration field.
    \endlist

    \section1 Performance considerations

    You can use fluidity and dynamic transitions as well as visual
    effects to great effect in a UI. However, you need to take some care when
    using some of the supported features because they can affect the
    performance of the UI.

    In general, animating a property will cause any bindings which reference
    that property to be re-evaluated. Usually, this is what you want, but in
    some cases it may be better to disable the binding prior to performing
    the animation and then reassign the binding once the animation has
    completed.

    Avoid running JavaScript during animation. For example, running a complex
    JavaScript expression for each frame of an x property animation should be
    avoided.

    Take special care when creating instances of the \uicontrol {Script Action}
    component because script animations are run in the main thread and can
    therefore cause frames to be skipped if they take too long to complete.

    \section1 Summary of the animation components

    The following table lists the components that you can use to animate
    component properties programmatically. They are available in
    \uicontrol Components > \uicontrol {Default Components} >
    \uicontrol {Animation}.

    \table
    \header
        \li Component
        \li Use case
    \row
        \li \uicontrol {Property Animation}
        \li Applying animation when the value of a property changes. Color
            and number animations are property animation types for specific
            purposes.
    \row
        \li \uicontrol {Property Action}
        \li Setting non-animated property values during an animation.
    \row
        \li \uicontrol {Color Animation}
        \li Applying animation when a color value changes.
    \row
        \li \uicontrol {Number Animation}
        \li Applying animation when a numerical value changes.
    \row
        \li \uicontrol {Parallel Animation}
        \li Running animations in parallel.
    \row
        \li \uicontrol {Sequential Animation}
        \li Running animations sequentially.
    \row
        \li \uicontrol {Pause Animation}
        \li Creating a step in a sequential animation where nothing happens for
            a specified duration.
    \row
        \li \uicontrol {Script Action}
        \li Executing JavaScript during an animation.
    \endtable

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