IUIAnimationPriorityComparison2

優先度の比較によってスケジューリングの競合を解決するメソッドを定義します。

1 つのアニメーション変数を複数のストーリーボードに含めることはできますが、複数のストーリーボードが同じ変数を同時にアニメーション化することはできません。

新しくスケジュールされたストーリーボードが、現在別のストーリーボードによってアニメーション化するようスケジュールされている 1 つ以上の変数をアニメーション化しようとすると、スケジューリングの競合が発生します。

どちらのストーリーボードが優先されるかを判断するために、アニメーションマネージャーはアプリケーションが提供する 1 つ以上の優先度比較ハンドラーの HasPriority メソッドを呼び出すことができます。

スケジュール済みのストーリーボードと新しいストーリーボードの相対的な優先度を判断します。

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

1 つのアニメーション変数を複数のストーリーボードに含めることはできますが、複数のストーリーボードが同じ変数を同時にアニメーション化することはできません。

新しいストーリーボードが、現在別のストーリーボードによってアニメーション化するようスケジュールされている 1 つ以上の変数をアニメーション化しようとすると、スケジューリングの競合が発生します。

どちらのストーリーボードが優先されるかを判断するために、アニメーションマネージャーはアプリケーションが提供する 1 つ以上の優先度比較ハンドラーの HasPriority メソッドを呼び出すことができます。

優先度比較オブジェクトの登録は任意です。既定では、失敗を回避するためにすべてのストーリーボードをトリミング、終了 (conclude)、または圧縮できますが、キャンセルすることはできません。また既定では、遅延を回避するためにストーリーボードがキャンセルされたりトリミングされたりすることはありません。

既定では、コールバックメソッド内から他のアニメーションメソッドを呼び出すと、その呼び出しは失敗し UI_E_ILLEGAL_REENTRANCY を返します。ただし、この既定の動作には例外があります。次のメソッドは HasPriority から正常に呼び出すことができます。

• IUIAnimationManager2::GetStoryboardFromTag
• IUIAnimationManager2::GetVariableFromTag
• IUIAnimationStoryboard::GetTag
• IUIAnimationVariable2::GetTag

競合の管理

スケジューリングの競合を解決するために、アニメーションマネージャーには次の選択肢があります。

• スケジュール済みストーリーボードがまだ再生を開始しておらず、IUIAnimationManager2::SetCancelPriorityComparison で登録された優先度比較オブジェクトが S_OK を返す場合、そのストーリーボードをキャンセルします。キャンセルされたストーリーボードはスケジュールから完全に削除されます。
• IUIAnimationManager2::SetTrimPriorityComparison で登録された優先度比較オブジェクトが S_OK を返す場合、スケジュール済みストーリーボードをトリミングします。新しいストーリーボードがスケジュール済みストーリーボードをトリミングすると、新しいストーリーボードがある変数のアニメーションを開始した時点で、スケジュール済みストーリーボードはその変数に影響を与えられなくなります。
• スケジュール済みストーリーボードが繰り返し回数 UI_ANIMATION_REPEAT_INDEFINITELY のループを含んでおり、IUIAnimationManager2::SetConcludePriorityComparison で登録された優先度比較オブジェクトが S_OK を返す場合、そのストーリーボードを終了 (conclude) します。ストーリーボードが終了されると、現在のループの繰り返しが完了し、その後ストーリーボードの残りの部分が再生されます。
• 圧縮の影響を受ける可能性があるすべてのスケジュール済みストーリーボードについて、IUIAnimationManager2::SetCompressPriorityComparison で登録された優先度比較オブジェクトが S_OK を返す場合、スケジュール済みストーリーボードおよび同じ変数をアニメーション化している他のストーリーボードを圧縮します。ストーリーボードが圧縮されると、対象のストーリーボードでは時間が一時的に加速され、より速く再生されます。

優先度比較オブジェクトによって上記のいずれの選択肢も許可されない場合、ストーリーボードのスケジューリングは失敗し、Windows Animation は呼び出し元アプリケーションに UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY を返します。

新しいストーリーボードが正常にスケジュールされるためには、許容される最長の遅延時間が経過する前に開始する必要がある点に注意してください。この時間は IUIAnimationStoryboard::SetLongestAcceptableDelay または IUIAnimationManager2::SetDefaultLongestAcceptableDelay によって決まります (どちらも呼び出されない場合、既定値は 0.0 秒です)。許容される最長の遅延時間が UI_ANIMATION_SECONDS_EVENTUALLY の場合は、有限の遅延であればすべて許容されます。

priorityEffect パラメーターは、HasPriority が S_FALSE を返した場合に新しいストーリーボードに及ぶ可能性のある影響を示します。priorityEffect が UI_ANIMATION_PRIORITY_EFFECT_FAILURE の場合、S_FALSE を返すと新しいストーリーボードのスケジューリングが失敗する可能性があります (ただし、別の優先度比較オブジェクトによって、アニメーションマネージャーが異なる方法で競合を解決できる場合もあります)。priorityEffect が UI_ANIMATION_PRIORITY_EFFECT_DELAY の場合、S_FALSE を返すことによる唯一の不利益は、HasPriority が S_OK を返した場合よりもストーリーボードの開始が遅くなる可能性があることだけです。

UI_ANIMATION_PRIORITY_EFFECT_DELAY が HasPriority に渡される場合、アニメーションマネージャーは、許容される最長の遅延時間が経過する前に新しいストーリーボードを開始できるとすでに判断しており、実質的にはストーリーボードをさらに早く開始すべきかどうかをアプリケーションに尋ねています。シナリオによっては、S_OK を返してアニメーションの遅延を減らすのが最善の場合があります。一方、可能な限りスケジュール済みのアニメーションを完了させる方が望ましい場合もあり、その際には HasPriority は S_FALSE を返すべきです。UI_ANIMATION_PRIORITY_EFFECT_DELAY が HasPriority に渡されるのは、アニメーションマネージャーがストーリーボードのキャンセルまたはトリミングを検討している場合のみです。