Metodo IUIAnimationPriorityComparison2::HasPriority (uianimation.h)

Articolo
03/13/2024

Determina la priorità relativa tra uno storyboard pianificato e un nuovo storyboard.

Sintassi

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

Parametri

[in] scheduledStoryboard

Storyboard attualmente pianificato.

[in] newStoryboard

Nuovo storyboard che interrompe lo storyboard pianificato specificato da scheduledStoryboard.

[in] priorityEffect

L'effetto potenziale su newStoryboard se scheduledStoryboard ha una priorità più alta.

Valore restituito

Restituisce quanto segue se l'operazione riesce; in caso contrario, un codice di errore HRESULT . Per un elenco di codici di errore, vedere Codici di errore di animazione di Windows .

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 uno storyboard diverso, si verifica un conflitto di pianificazione.

Per determinare quale storyboard ha priorità, lo strumento di gestione animazioni può chiamare il metodo HasPriority su uno o più gestori di confronto con priorità forniti dall'applicazione.

La registrazione degli oggetti di confronto con priorità è facoltativa. Per impostazione predefinita, è possibile tagliare, concludere o comprimere tutti gli storyboard 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 genera l'esito negativo della chiamata e restituisce UI_E_ILLEGAL_REENTRANCY. Tuttavia, esistono eccezioni a questo valore predefinito. I metodi seguenti possono essere chiamati correttamente da HasPriority:

Gestione dei conflitti

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

Annullare lo storyboard pianificato se non è stato avviato la riproduzione e l'oggetto di confronto priorità registrato con IUIAnimationManager2::SetCancelPriorityComparison restituisce S_OK. Gli storyboard annullati vengono completamente rimossi dalla pianificazione.
Tagliare lo storyboard pianificato se l'oggetto di confronto priorità registrato con IUIAnimationManager2::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.
Concludere lo storyboard pianificato se lo storyboard pianificato contiene un ciclo con un numero di ripetizioni di UI_ANIMATION_REPEAT_INDEFINITELY e l'oggetto di confronto priorità registrato con IUIAnimationManager2::SetConcludePriorityComparison restituisce S_OK. Se lo storyboard viene concluso, la ripetizione corrente del ciclo viene completata e il promemoria dello storyboard viene riprodotto.
Comprimere lo storyboard pianificato e qualsiasi altro storyboard che anima le stesse variabili, se l'oggetto di confronto priorità registrato con IUIAnimationManager2::SetCompressPriorityComparison restituisce S_OK per tutti gli storyboard pianificati che potrebbero essere interessati dalla compressione. Quando gli storyboard vengono compressi, il tempo viene temporaneamente accelerato per gli storyboard interessati, in modo che vengano riprodotti più velocemente.

Se nessuna delle opzioni precedenti è consentita dagli oggetti di confronto prioritari, 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 pianificare correttamente il nuovo storyboard, deve iniziare prima che sia trascorso il ritardo accettabile più lungo. Ciò è determinato da IUIAnimationStoryboard::SetLongestAcceptableDelay o IUIAnimationManager2::SetDefaultLongestAcceptableDelay (se non viene chiamato nessuno dei due, 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 provocherà un errore nella pianificazione del nuovo storyboard. È anche possibile che la gestione animazione possa risolvere il conflitto in modo diverso da un altro oggetto di confronto prioritario. Se priorityEffect è UI_ANIMATION_PRIORITY_EFFECT_DELAY, l'unico aspetto negativo della restituzione di S_FALSE è che lo storyboard potrebbe iniziare più tardi di quanto avrebbe dovuto se HasPriority avesse restituito S_OK.

Quando UI_ANIMATION_PRIORITY_EFFECT_DELAY viene passato a HasPriority, lo strumento di gestione animazioni ha già determinato che può pianificare il nuovo storyboard per iniziare prima che sia trascorso il ritardo accettabile più lungo, ma è in effetti chiedere all'applicazione se lo storyboard deve iniziare anche in precedenza. In alcuni scenari potrebbe essere preferibile ridurre la latenza di un'animazione restituendo S_OK. In altri casi, potrebbe essere preferibile lasciare che le animazioni pianificate vengano completate quando possibile, nel qual caso HasPriority deve restituire S_FALSE. UI_ANIMATION_PRIORITY_EFFECT_DELAY viene passato a HasPriority solo quando il gestore di animazioni sta valutando l'annullamento o il taglio di uno storyboard.

Requisiti

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