IUIAnimationPriorityComparison2::HasPriority-Methode (uianimation.h)

Artikel
03/06/2024

Bestimmt die relative Priorität zwischen einem geplanten Storyboard und einem neuen Storyboard.

Syntax

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

Parameter

[in] scheduledStoryboard

Das derzeit geplante Storyboard.

[in] newStoryboard

Das neue Storyboard, das das durch scheduledStoryboard angegebene geplante Storyboard unterbricht.

[in] priorityEffect

Die potenzielle Auswirkung auf newStoryboard bei scheduledStoryboard hat eine höhere Priorität.

Rückgabewert

Gibt Folgendes zurück, wenn dies erfolgreich war: andernfalls ein HRESULT-Fehlercode . Eine Liste der Fehlercodes finden Sie unter Fehlercodes für die Windows-Animation .

Rückgabecode	BESCHREIBUNG
S_OK	newStoryboard hat Priorität.
S_FALSE	scheduledStoryboard hat Priorität.

Hinweise

Eine einzelne Animationsvariable kann in mehreren Storyboards enthalten sein, aber mehrere Storyboards können dieselbe Variable nicht gleichzeitig animieren.

Wenn ein neues Storyboard versucht, eine oder mehrere Variablen zu animieren, die derzeit für die Animation durch ein anderes Storyboard geplant sind, tritt ein Terminplanungskonflikt auf.

Um zu bestimmen, welches Storyboard Priorität hat, kann der Animations-Manager die HasPriority-Methode für einen oder mehrere von der Anwendung bereitgestellte Prioritätsvergleichshandler aufrufen.

Die Registrierung von Prioritätsvergleichsobjekten ist optional. Standardmäßig können alle Storyboards gekürzt, abgeschlossen oder komprimiert werden, um einen Fehler zu verhindern, aber keines kann abgebrochen werden, und standardmäßig werden keine Storyboards abgebrochen oder gekürzt, um eine Verzögerung zu verhindern.

Standardmäßig führt ein Aufruf, der in einer Rückrufmethode für eine andere Animationsmethode ausgeführt wird, dazu, dass der Aufruf fehlschlägt und UI_E_ILLEGAL_REENTRANCY zurückgibt. Es gibt jedoch Ausnahmen für diesen Standardwert. Die folgenden Methoden können erfolgreich von HasPriority aufgerufen werden:

Konfliktverwaltung

Um einen Terminplanungskonflikt zu beheben, verfügt der Animations-Manager über die folgenden Optionen:

Brechen Sie das geplante Storyboard ab, wenn es nicht mit der Wiedergabe begonnen hat und das bei IUIAnimationManager2::SetCancelPriorityComparison registrierte Prioritätsvergleichsobjekt S_OK zurückgibt. Abgebrochene Storyboards werden vollständig aus dem Zeitplan entfernt.
Kürzen Sie das geplante Storyboard, wenn das bei IUIAnimationManager2::SetTrimPriorityComparison registrierte Prioritätsvergleichsobjekt S_OK zurückgibt. Wenn das neue Storyboard das geplante Storyboard schneidet, kann sich das geplante Storyboard nicht mehr auf eine Variable auswirken, wenn das neue Storyboard beginnt, diese Variable zu animieren.
Schließen Sie das geplante Storyboard ab, wenn das geplante Storyboard eine Schleife mit einer Wiederholungsanzahl von UI_ANIMATION_REPEAT_INDEFINITELY enthält und das Mit IUIAnimationManager2::SetConcludePriorityComparison registrierte Prioritätsvergleichsobjekt S_OK zurückgibt. Wenn das Storyboard abgeschlossen ist, wird die aktuelle Wiederholung der Schleife abgeschlossen, und die Erinnerung an das Storyboard wird dann wiedergegeben.
Komprimieren Sie das geplante Storyboard und alle anderen Storyboards, die dieselben Variablen animieren, wenn das mit IUIAnimationManager2::SetCompressPriorityComparison registrierte Prioritätsvergleichsobjekt S_OK für alle geplanten Storyboards zurückgibt, die von der Komprimierung betroffen sein könnten. Wenn die Storyboards komprimiert werden, wird die Zeit für betroffene Storyboards vorübergehend beschleunigt, sodass sie schneller wiedergegeben werden.

Wenn keine der vorherigen Optionen von den Prioritätsvergleichsobjekten zulässig ist, schlägt der Versuch, das Storyboard zu planen, fehl, und Windows-Animation gibt UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY an die aufrufende Anwendung zurück.

Beachten Sie, dass das neue Storyboard damit erfolgreich geplant werden kann, bevor die längste akzeptable Verzögerung abgelaufen ist. Dies wird durch IUIAnimationStoryboard::SetLongestAcceptableDelay oder IUIAnimationManager2::SetDefaultLongestAcceptableDelay bestimmt (wenn keiner aufgerufen wird, ist der Standardwert 0,0 Sekunden). Wenn die längste akzeptable Verzögerung UI_ANIMATION_SECONDS_EVENTUALLY ist, ist jede endliche Verzögerung ausreichend.

Der parameter priorityEffect beschreibt die möglichen Auswirkungen auf das neue Storyboard, wenn HasPriorityS_FALSE zurückgeben würde. Wenn priorityEffectUI_ANIMATION_PRIORITY_EFFECT_FAILURE ist, ist es möglich, dass die Rückgabe von S_FALSE zu einem Fehler beim Planen des neuen Storyboards führt. (Es ist auch möglich, dass der Animations-Manager den Konflikt durch ein anderes Prioritätsvergleichsobjekt auf andere Weise auflösen kann.) Wenn priorityEffectUI_ANIMATION_PRIORITY_EFFECT_DELAY ist, besteht der einzige Nachteil der Rückgabe von S_FALSE darin, dass das Storyboard möglicherweise später beginnt, als wenn HasPriorityS_OK zurückgegeben hätte.

Wenn UI_ANIMATION_PRIORITY_EFFECT_DELAY an HasPriority übergeben wird, hat der Animations-Manager bereits festgestellt, dass er den Beginn des neuen Storyboards planen kann, bevor die längste akzeptable Verzögerung abgelaufen ist. Es wird jedoch tatsächlich die Anwendung gefragt, ob das Storyboard noch früher beginnen sollte. In einigen Szenarien kann es am besten sein, die Latenz einer Animation zu reduzieren, indem Sie S_OK zurückgeben. In anderen Fällen kann es vorzuziehen sein, geplante Animationen nach Möglichkeit abschließen zu lassen. In diesem Fall sollte HasPriorityS_FALSE zurückgeben. UI_ANIMATION_PRIORITY_EFFECT_DELAY wird nur an HasPriority übergeben, wenn der Animations-Manager erwägt, ein Storyboard abzubrechen oder zu kürzen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8, Windows 7 und Platform Update für Windows 7 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Nicht unterstützt
Zielplattform	Windows
Kopfzeile	uianimation.h
DLL	UIAnimation.dll