Edit

Create Animation Variables

  • Article

An application must create an animation variable for each visual characteristic that is to be animated using Windows Animation.

Overview

Animation variables are created using the animation manager, and the application should retain a reference to each for as long as it is needed. Your application will generally create each animation variable at the same time as the visual object it animates.

When an animation variable is created, its initial value must be specified. Thereafter, its value can only be altered by scheduling storyboards that animate it.

Animation variables are passed as parameters when storyboards are constructed, so the application should not release them until the visual characteristics they represent no longer need to be animated, typically when the associated visual objects are about to be destroyed.

Example Code

Animating Colors

The following example code is taken from MainWindow.cpp in the Windows Animation samples Application-Driven Animation and Timer-Driven Animation. In the example, three animation variables are created using CreateAnimationVariable to represent background colors. The code also uses the SetLowerBound and SetUpperBound methods to control the value of the animation variable.

const DOUBLE INITIAL_RED = COLOR_MAX;
const DOUBLE INITIAL_GREEN = COLOR_MAX;
const DOUBLE INITIAL_BLUE = COLOR_MAX;

HRESULT hr = m_pAnimationManager->CreateAnimationVariable(
    INITIAL_RED,
    &m_pAnimationVariableRed
    );
if (SUCCEEDED(hr))
{
    hr = m_pAnimationVariableRed->SetLowerBound(COLOR_MIN);
    if (SUCCEEDED(hr))
    {
        hr = m_pAnimationVariableRed->SetUpperBound(COLOR_MAX);
        if (SUCCEEDED(hr))
        {
            hr = m_pAnimationManager->CreateAnimationVariable(
                INITIAL_GREEN,
                &m_pAnimationVariableGreen
                );
            if (SUCCEEDED(hr))
            {
                hr = m_pAnimationVariableGreen->SetLowerBound(COLOR_MIN);
                if (SUCCEEDED(hr))
                {
                    hr = m_pAnimationVariableGreen->SetUpperBound(COLOR_MAX);
                    if (SUCCEEDED(hr))
                    {
                        hr = m_pAnimationManager->CreateAnimationVariable(
                            INITIAL_BLUE,
                            &m_pAnimationVariableBlue
                            );
                        if (SUCCEEDED(hr))
                        {
                            hr = m_pAnimationVariableBlue->SetLowerBound(COLOR_MIN);
                            if (SUCCEEDED(hr))
                            {
                                hr = m_pAnimationVariableBlue->SetUpperBound(COLOR_MAX);
                            }
                        }
                    }
                }
            }
        }
    }
}

Note the following definitions from MainWindow.h.

class CMainWindow
{

    ...

private:

    // Animated Variables

    IUIAnimationVariable *m_pAnimationVariableRed;
    IUIAnimationVariable *m_pAnimationVariableGreen;
    IUIAnimationVariable *m_pAnimationVariableBlue;

    ...

};

Animating x and y Coordinates

The following example code is taken from Thumbnail.cpp in the Windows Animation Grid Layout Sample; see the CMainWindow::CreateAnimationVariables method. Two animation variables are created to represent the X and Y coordinates of each object.

// Create the animation variables for the x and y coordinates

hr = m_pAnimationManager->CreateAnimationVariable(
    xInitial,
    &m_pAnimationVariableX
    );

if (SUCCEEDED(hr))
{
    hr = m_pAnimationManager->CreateAnimationVariable(
        yInitial,
        &m_pAnimationVariableY
        );

    ...

}

Note the following definitions from Thumbnail.h.

class CThumbnail
{
public:

    ...

    // X and Y Animation Variables

    IUIAnimationVariable *m_pAnimationVariableX;
    IUIAnimationVariable *m_pAnimationVariableY;

    ...

};

Animation variables are floating-point numbers, but their values can be fetched as integers, too. By default, each value will be rounded to the nearest integer, but it is possible to override the rounding mode used for a variable. The following example code uses the SetRoundingMode method to specify that the values should always be rounded down.

hr = m_pAnimationVariableX->SetRoundingMode(
    UI_ANIMATION_ROUNDING_MODE_FLOOR
    );
if (SUCCEEDED(hr))
{
    hr = m_pAnimationVariableY->SetRoundingMode(
        UI_ANIMATION_ROUNDING_MODE_FLOOR
        );

    ...

}

Previous Step

Before starting this step, you should have completed this step: Create the Main Animation Objects.

Next Step

After completing this step, the next step is: Update the Animation Manager and Draw Frames.

IUIAnimationManager::CreateAnimationVariable

IUIAnimationVariable::SetLowerBound

IUIAnimationVariable::SetRoundingMode

IUIAnimationVariable::SetUpperBound

Windows Animation Overview