IUIAnimationPriorityComparison2::HasPriority メソッド (uianimation.h)

[アーティクル]
08/26/2023

スケジュールされたストーリーボードと新しいストーリーボードの間の相対的な優先順位を決定します。

構文

HRESULT HasPriority(
  [in] IUIAnimationStoryboard2      *scheduledStoryboard,
  [in] IUIAnimationStoryboard2      *newStoryboard,
  [in] UI_ANIMATION_PRIORITY_EFFECT priorityEffect
);

パラメーター

[in] scheduledStoryboard

現在スケジュールされているストーリーボード。

[in] newStoryboard

scheduledStoryboard で指定されたスケジュールされたストーリーボードを中断している新しいストーリーボード。

[in] priorityEffect

scheduledStoryboard の優先度が高い場合の newStoryboard に対する潜在的な影響。

戻り値

成功した場合は、次を返します。それ以外の場合は HRESULT エラーコード。エラーコードの一覧については、「 Windows アニメーションエラーコード」を参照してください。

リターンコード	説明
S_OK	newStoryboard には優先度があります。
S_FALSE	scheduledStoryboard には優先度があります。

注釈

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

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

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

優先度比較オブジェクトの登録は省略可能です。既定では、失敗を防ぐためにすべてのストーリーボードをトリミング、終了、または圧縮できますが、取り消せるものはなく、既定では遅延を防ぐためにストーリーボードは取り消されたりトリミングされたりしません。

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

競合管理

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

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

優先度比較オブジェクトで上記のどのオプションも許可されていない場合、ストーリーボードをスケジュールしようとすると失敗し、Windows アニメーションは呼び出し元のアプリケーションに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 に渡されます。

要件

要件	値
サポートされている最小のクライアント	Windows 8、Windows 7、および Windows 7 用プラットフォーム更新プログラム [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	サポートなし
対象プラットフォーム	Windows
ヘッダー	uianimation.h
[DLL]	UIAnimation.dll