IUIAnimationPriorityComparison

スケジューリングの競合を解決するためにアニメーションマネージャーが使用する、優先度比較用のメソッドを定義します。

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

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

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

新しいストーリーボードが、スケジュール済みのストーリーボードより優先されるかどうかを判断します。

このメソッドは次のいずれかの値を返すことがあります。

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

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

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

優先度比較オブジェクトの登録は任意です。既定では、すべてのストーリーボードは失敗を防ぐためにトリム、終結、圧縮の対象となり得ますが、キャンセルされることはありません。また既定では、遅延を防ぐためにキャンセルまたはトリムされるストーリーボードはありません。

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

• IUIAnimationManager::GetStoryboardFromTag
• IUIAnimationManager::GetVariableFromTag
• IUIAnimationStoryboard::GetTag
• IUIAnimationVariable::GetTag

競合の管理

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

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

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

なお、新しいストーリーボードが正常にスケジュールされるには、許容される最長の遅延が経過する前に開始する必要があります。これは IUIAnimationStoryboard::SetLongestAcceptableDelay または IUIAnimationManager::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 を返してアニメーションの待ち時間を短縮するのが最善の場合があります。一方、可能な限りスケジュール済みのアニメーションを完了させる方が望ましい場合もあり、その場合は S_FALSE を返す必要があります。UI_ANIMATION_PRIORITY_EFFECT_DELAY が HasPriority に渡されるのは、アニメーションマネージャーがストーリーボードのキャンセルまたはトリムを検討している場合のみです。