Metodo IUIAnimationPriorityComparison::HasPriority (uianimation.h)

Articolo
08/26/2023

Determina se una nuova storyboard ha priorità su uno storyboard pianificato.

Sintassi

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

Parametri

[in] scheduledStoryboard

Storyboard attualmente pianificato.

[in] newStoryboard

Il nuovo storyboard che interrompe lo storyboard pianificato specificato in scheduledStoryboard.

[in] priorityEffect

L'effetto potenziale per newStoryboard se scheduledStoryboard ha una priorità maggiore.

Valore restituito

Questo metodo può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	newStoryboard ha priorità.
S_FALSE	scheduledStoryboard ha priorità.

Commenti

Una singola variabile di animazione può essere inclusa in più storyboard, ma più storyboard non possono animare contemporaneamente la stessa variabile.

Se un nuovo storyboard tenta di animare una o più variabili attualmente pianificate per l'animazione da un storyboard diverso, si verifica un conflitto di pianificazione.

Per determinare quale storyboard ha priorità, la gestione animazioni può chiamare HasPriority in uno o più gestori di confronto con priorità forniti dall'applicazione.

La registrazione degli oggetti di confronto con priorità è facoltativa. Per impostazione predefinita, tutti i storyboard possono essere eliminati, conclusi o compressi per evitare errori, ma nessuno può essere annullato e per impostazione predefinita nessun storyboard verrà annullato o tagliato per evitare un ritardo.

Per impostazione predefinita, una chiamata effettuata in un metodo di callback a qualsiasi altro metodo di animazione comporta l'esito negativo della chiamata e la restituzione di UI_E_ILLEGAL_REENTRANCY. Tuttavia, esistono eccezioni a questo valore predefinito. I metodi seguenti possono essere chiamati correttamente da HasPriority:

Gestione della contesa

Per risolvere un conflitto di pianificazione, la gestione animazione ha le opzioni seguenti:

Annullare lo storyboard pianificato se non è stato avviato la riproduzione e l'oggetto di confronto con priorità registrato con IUIAnimationManager::SetCancelPriorityComparison restituisce S_OK. Gli storyboard annullati vengono completamente rimossi dalla pianificazione.
Tagliare lo storyboard pianificato se l'oggetto di confronto di priorità registrato con IUIAnimationManager::SetTrimPriorityComparison restituisce S_OK. Se il nuovo storyboard taglia lo storyboard pianificato, lo storyboard pianificato non può più influire su una variabile quando il nuovo storyboard inizia ad animare tale variabile.
Terminare lo storyboard pianificato se il storyboard pianificato contiene un ciclo con un numero di ripetizioni di UI_ANIMATION_REPEAT_INDEFINITELY e l'oggetto di confronto della priorità registrato con IUIAnimationManager::SetConcludePriorityComparison restituisce S_OK. Se il storyboard viene concluso, la ripetizione corrente del ciclo viene completata e il promemoria del storyboard viene riprodotto.
Comprimere lo storyboard pianificato e qualsiasi altro storyboard che anima le stesse variabili, se l'oggetto di confronto prioritario registrato con IUIAnimationManager::SetCompressPriorityComparison restituisce S_OK per tutti gli storyboard pianificati che potrebbero essere interessati dalla compressione. Quando i storyboard vengono compressi, il tempo viene temporaneamente accelerato per gli storyboard interessati, quindi giocano più velocemente.

Se nessuna delle opzioni precedenti è consentita dagli oggetti di confronto con priorità, il tentativo di pianificare lo storyboard ha esito negativo e l'animazione di Windows restituisce UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY all'applicazione chiamante.

Si noti che per la pianificazione del nuovo storyboard, deve iniziare prima che il ritardo accettabile più lungo sia trascorso. Ciò è determinato da IUIAnimationStoryboard::SetLongestAcceptableDelay o IUIAnimationManager::SetDefaultLongestAcceptableDelay (se non viene chiamato nessuno dei due secondi, il valore predefinito è 0,0 secondi). Se il ritardo accettabile più lungo è UI_ANIMATION_SECONDS_EVENTUALLY, qualsiasi ritardo finito sarà sufficiente.

Il parametro priorityEffect descrive l'effetto possibile sul nuovo storyboard se HasPriority dovesse restituire S_FALSE. Se priorityEffect è UI_ANIMATION_PRIORITY_EFFECT_FAILURE, è possibile che la restituzione di S_FALSE comporterà un errore per pianificare il nuovo storyboard (è anche possibile che il responsabile dell'animazione possa risolvere il conflitto in modo diverso da un altro oggetto di confronto prioritario). Se priorityEffect è UI_ANIMATION_PRIORITY_EFFECT_DELAY, l'unico lato negativo della restituzione S_FALSE è che il storyboard potrebbe iniziare più tardi di quanto avrebbe restituito HasPriority S_OK.

Quando UI_ANIMATION_PRIORITY_EFFECT_DELAY viene passato a HasPriority, il responsabile dell'animazione ha già determinato che può pianificare il nuovo storyboard in modo che inizierà prima che il ritardo accettabile più lungo sia trascorso, ma è in effetti chiedere all'applicazione se il storyboard dovrebbe iniziare anche in precedenza. In alcuni scenari, potrebbe essere consigliabile ridurre la latenza di un'animazione restituendo S_OK. In altri casi, potrebbe essere preferibile lasciare che le animazioni pianificate vengano completate ogni volta che è possibile, in questo caso S_FALSE deve essere restituito. UI_ANIMATION_PRIORITY_EFFECT_DELAY viene passato solo a HasPriority quando il responsabile dell'animazione sta considerando l'annullamento o l'eliminazione di uno storyboard.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7, Windows Vista e Aggiornamento della piattaforma per Windows Vista [app desktop \| App UWP]
Server minimo supportato	Nessuno supportato
Piattaforma di destinazione	Windows
Intestazione	uianimation.h
DLL	UIAnimation.dll