IUIAnimationManager

アニメーションを作成および管理するための中心的なインターフェイスを提供する、アニメーションマネージャーを定義します。

IUIAnimationManager は、アニメーションの中心的な制御オブジェクトを定義します。

通常、クライアントアプリケーションのすべてのアニメーションの構成、スケジュール、管理には、単一の IUIAnimationManager インスタンスを使用します。

IUIAnimationVariable、IUIAnimationTransition、IUIAnimationStoryboard は、アニメーションを構築するための主要なコンポーネントです。

これらのコンポーネントの作成と管理には IUIAnimationManager を使用します。

例

アニメーションマネージャーオブジェクトを作成する例については、Create the Main Animation Objects を参照してください。

新しいアニメーション変数を作成します。(IUIAnimationManager.CreateAnimationVariable)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

アニメーション変数の初期値は、変数の作成時に指定します。アニメーション変数の作成後は、その値を直接変更することはできません。値の更新はアニメーションマネージャーを通じて行う必要があります。

通常、アニメーション化する視覚的特性ごとにアニメーション変数を作成します。たとえば、ウィンドウ内を自由に移動できるオブジェクトの X 座標と Y 座標のために、アプリケーションが 2 つのアニメーション変数を作成する、といった具合です。

例

例については、Create Animation Variables を参照してください。

遷移(トランジション)を 1 つだけ含むストーリーボードを作成してスケジュールします。(IUIAnimationManager.ScheduleTransition)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドは、ストーリーボードを作成し、指定された遷移を指定されたアニメーション変数に適用したうえで、そのストーリーボードをスケジュールします。

例

次の例では、指定した遷移とアニメーション変数に対するストーリーボードを作成します。

// Get the current time and schedule a single-transition storyboard

UI_ANIMATION_SECONDS secondsNow;
hr = m_pAnimationTimer->GetTime(
    &secondsNow
    );
if (SUCCEEDED(hr))
{
    hr = m_pAnimationManager->ScheduleTransition(
        m_pAnimationVariableY,
        pTransitionParabolic,
        secondsNow
        );
    ...
}

新しいストーリーボードを作成します。(IUIAnimationManager.CreateStoryboard)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

ストーリーボードでは、多数のアニメーション変数に対する複雑な協調的更新を指定できます。これらの更新は順次または並行して行われ、ストーリーボード内で同期が保たれることが保証されます。ストーリーボードは、作成し、アニメーション変数への遷移を追加したうえで、スケジュールします。

例

例については、Create a Storyboard and Add Transitions を参照してください。

指定された時間内に、アクティブなすべてのストーリーボードを終了させます。(IUIAnimationManager.FinishAllStoryboards)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

FinishAllStoryboards を呼び出すと、アクティブなすべてのストーリーボードが指定された完了期限内に終了するようになります。期限を超えて再生される予定のストーリーボードは圧縮されます。

ストーリーボードは、その状態が UI_ANIMATION_STORYBOARD_PLAYING または UI_ANIMATION_STORYBOARD_SCHEDULED の場合にアクティブと見なされます。

アクティブなすべてのストーリーボードを破棄します。(IUIAnimationManager.AbandonAllStoryboards)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドの呼び出しは、アクティブな各ストーリーボードに対して IUIAnimationStoryboard::Abandon メソッドを呼び出すことと同等です。

ストーリーボードは、その状態が UI_ANIMATION_STORYBOARD_PLAYING または UI_ANIMATION_STORYBOARD_SCHEDULED の場合にアクティブと見なされます。

すべてのアニメーション変数の値を更新します。(IUIAnimationManager.Update)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。 エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドを呼び出すと、アニメーションマネージャーが timeNow まで進み、必要に応じてストーリーボードの状態が変化し、アニメーション変数が適切な補間値に更新されます。アニメーションマネージャーが一時停止している場合、ストーリーボードも変数も更新されません。アニメーションモードが UI_ANIMATION_MODE_DISABLED の場合、スケジュールされているすべてのストーリーボードは直ちに再生を終了します。この呼び出し中にいずれかの変数の値が変化した場合、updateResult の値は UI_ANIMATION_UPDATE_VARIABLES_CHANGED になります。変化しなかった場合は UI_ANIMATION_UPDATE_NO_CHANGE になります。

例

次の例では、現在の時刻でアニメーションマネージャーを更新します。その他の例については、Update the Animation Manager and Draw Frames を参照してください。

// Update the animation manager with the current time
UI_ANIMATION_SECONDS secondsNow;
hr = m_pAnimationTimer->GetTime(
    &secondsNow
    );
if (SUCCEEDED(hr))
{
    UI_ANIMATION_UPDATE_RESULT updateResult;
    hr = m_pAnimationManager->Update(
        secondsNow,
        &updateResult
        );
    if (SUCCEEDED(hr))
    {
        if (updateResult == UI_ANIMATION_UPDATE_VARIABLES_CHANGED)
        {
            ...
        }
    }
}

指定されたタグを持つアニメーション変数を取得します。(IUIAnimationManager.GetVariableFromTag)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

タグとは、整数の識別子(id)と COM オブジェクト(object)の組み合わせです。アプリケーションはタグを使用してアニメーション変数やストーリーボードを識別できます。タグのオブジェクト部分としては NULL も有効です。したがって、object パラメーターは NULL でもかまいません。

タグは必ずしも一意ではありません。指定されたタグを持つアニメーション変数が複数存在する場合、このメソッドは UI_E_AMBIGUOUS_MATCH を返します。

指定されたタグを持つストーリーボードを取得します。(IUIAnimationManager.GetStoryboardFromTag)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

タグとは、整数の識別子(id)と COM オブジェクト(object)の組み合わせです。アプリケーションはタグを使用してアニメーション変数やストーリーボードを識別できます。タグのオブジェクト部分としては NULL も有効です。したがって、object パラメーターは NULL でもかまいません。

タグは必ずしも一意ではありません。指定されたタグを持つストーリーボードが複数存在する場合、このメソッドは UI_E_AMBIGUOUS_MATCH を返します。

アニメーションマネージャーの状態を取得します。(IUIAnimationManager.GetStatus)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

アニメーションモードを設定します。(IUIAnimationManager.SetAnimationMode)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドは、アニメーションをグローバルに有効または無効にするために使用します。アニメーションが無効になっている間、すべてのストーリーボードはスケジュールされた時点で直ちに終了します。既定のモードは UI_ANIMATION_MODE_SYSTEM_DEFAULT で、アプリケーションでアニメーションを有効にするか無効にするかを Windows が判断します。

すべてのアニメーションを一時停止します。(IUIAnimationManager.Pause)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

アニメーションマネージャーが一時停止すると、その状態は UI_ANIMATION_MANAGER_IDLE に設定されます。

すべてのアニメーションを再開します。(IUIAnimationManager.Resume)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

アニメーションマネージャーが再開され、少なくとも 1 つのアニメーションがスケジュール済みまたは再生中である場合、その状態は UI_ANIMATION_MANAGER_BUSY に設定されます。

アニメーションマネージャーの状態更新に対するハンドラーを指定します。(IUIAnimationManager.SetManagerEventHandler)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

handler パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この方法は、IUIAnimationManager::Shutdown メソッドを呼び出さずに参照循環を断ち切るうえで不可欠となる場合があります。

例

例については、Update the Animation Manager and Draw Frames を参照してください。

スケジュール済みのストーリーボードをキャンセルできるかどうかを判断するために呼び出される、優先度比較ハンドラーを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドで優先度比較ハンドラーを設定すると、スケジュールの競合をストーリーボードのキャンセルによって解決できる場合を、アプリケーションが指定できるようになります。

スケジュール済みのストーリーボードは、まだ再生が開始されておらず、かつこのメソッドで登録された優先度比較オブジェクトが S_OK を返す場合にのみキャンセルできます。キャンセルされたストーリーボードはスケジュールから完全に削除されます。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡された優先度比較ハンドラーオブジェクトへの参照を解放します。この方法は、IUIAnimationManager::Shutdown メソッドを呼び出さずに参照循環を断ち切るうえで不可欠となる場合があります。

スケジュール済みのストーリーボードをトリミングできるかどうかを判断するために呼び出される、優先度比較ハンドラーを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドで優先度比較ハンドラーを設定すると、スケジュールの競合をスケジュール済みストーリーボードのトリミングによって解決できる場合を、アプリケーションが指定できるようになります。

スケジュール済みのストーリーボードは、このメソッドで登録された優先度比較オブジェクトが S_OK を返す場合にのみトリミングできます。新しいストーリーボードがスケジュール済みストーリーボードをトリミングした場合、新しいストーリーボードがある変数のアニメーションを開始した時点以降、スケジュール済みストーリーボードはその変数に影響を与えられなくなります。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この方法は、IUIAnimationManager::Shutdown メソッドを呼び出さずに参照循環を断ち切るうえで不可欠となる場合があります。

スケジュール済みのストーリーボードを圧縮できるかどうかを判断するために呼び出される、優先度比較ハンドラーを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドで優先度比較ハンドラーを設定すると、スケジュールの競合を、スケジュール済みストーリーボードおよび同じ変数をアニメーション化する他のストーリーボードを圧縮することで解決できる場合を、アプリケーションが指定できるようになります。

ストーリーボードを圧縮できるのは、圧縮の影響を受ける他のすべてのスケジュール済みストーリーボードについて、このメソッドで登録された優先度比較オブジェクトが S_OK を返す場合のみです。ストーリーボードが圧縮されると、影響を受けるストーリーボードの時間が一時的に加速され、再生が速くなります。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この方法は、IUIAnimationManager::Shutdown メソッドを呼び出さずに参照循環を断ち切るうえで不可欠となる場合があります。

スケジュール済みのストーリーボードを終結(conclude)できるかどうかを判断するために呼び出される、優先度比較ハンドラーを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドで優先度比較ハンドラーを設定すると、スケジュールの競合をスケジュール済みストーリーボードの終結によって解決できる場合を、アプリケーションが指定できるようになります。

スケジュール済みのストーリーボードを終結できるのは、そのストーリーボードが繰り返し回数 UI_ANIMATION_REPEAT_INDEFINITELY のループを含み、かつこのメソッドで登録された優先度比較オブジェクトが S_OK を返す場合のみです。ストーリーボードが終結されると、現在のループの繰り返しが完了し、その後ストーリーボードの残りの部分が再生されます。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この方法は、IUIAnimationManager::Shutdown メソッドを呼び出さずに参照循環を断ち切るうえで不可欠となる場合があります。

既定の許容アニメーション遅延を設定します。これは、ストーリーボードが開始されるまでに経過してもよい時間の長さです。(IUIAnimationManager.SetDefaultLongestAcceptableDelay)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
エラーコードの一覧については、Windows Animation Error Codes を参照してください。

ストーリーボードが正常にスケジュールされるには、許容される最長の遅延が経過する前に開始される必要があります。この遅延は次の順序で決定されます。まず、対象のストーリーボードに対して IUIAnimationStoryboard::SetLongestAcceptableDelay を呼び出して設定された遅延値、次にこのメソッドを呼び出して設定された遅延値、どちらのメソッドも呼び出されていない場合は 0.0 です。

アニメーションマネージャーおよび関連するすべてのオブジェクトをシャットダウンします。(IUIAnimationManager.Shutdown)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

このメソッドを呼び出すと、アニメーションマネージャーおよびそれが作成したすべてのオブジェクトに対して、 他のオブジェクトへのポインターをすべて解放するよう指示します。IUIAnimationManager::Shutdown を呼び出した後は、アニメーションマネージャーやそれが作成したオブジェクトに対して他のメソッドを呼び出すことはできません。アプリケーションがアニメーションオブジェクトを含む参照循環を生じさせている可能性がある場合、このメソッドを呼び出してクリーンアップできます。