Método IUIAnimationPriorityComparison::HasPriority (uianimation.h)

Artículo
03/08/2023

Determina si un nuevo guión gráfico tiene prioridad sobre un guión gráfico programado.

Sintaxis

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

Parámetros

[in] scheduledStoryboard

Guión gráfico programado actualmente.

[in] newStoryboard

Nuevo guión gráfico que está interrumpiendo el guión gráfico programado especificado en scheduledStoryboard.

[in] priorityEffect

El posible efecto en newStoryboard si scheduledStoryboard tiene una prioridad más alta.

Valor devuelto

Este método puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	newStoryboard tiene prioridad.
S_FALSE	scheduledStoryboard tiene prioridad.

Comentarios

Se puede incluir una sola variable de animación en varios guiones gráficos, pero varios guiones gráficos no pueden animar la misma variable al mismo tiempo.

Si un nuevo guión gráfico intenta animar una o varias variables programadas actualmente para la animación por otro guión gráfico, se produce un conflicto de programación.

Para determinar qué guión gráfico tiene prioridad, el administrador de animaciones puede llamar a HasPriority en uno o varios controladores de comparación de prioridad proporcionados por la aplicación.

El registro de objetos de comparación de prioridad es opcional. De forma predeterminada, todos los guiones gráficos se pueden recortar, concluir o comprimir para evitar errores, pero no se puede cancelar ninguno y, de forma predeterminada, no se cancelarán ni recortarán guiones gráficos para evitar un retraso.

De forma predeterminada, una llamada realizada en un método de devolución de llamada a cualquier otro método de animación produce un error en la llamada y devuelve UI_E_ILLEGAL_REENTRANCY. Sin embargo, hay excepciones a este valor predeterminado. Se puede llamar correctamente a los métodos siguientes desde HasPriority:

Administración de contención

Para resolver un conflicto de programación, el administrador de animaciones tiene las siguientes opciones:

Cancele el guión gráfico programado si no ha empezado a reproducirse y el objeto de comparación de prioridad registrado con IUIAnimationManager::SetCancelPriorityComparison devuelve S_OK. Los guiones gráficos cancelados se quitan completamente de la programación.
Recorte el guión gráfico programado si el objeto de comparación de prioridad registrado con IUIAnimationManager::SetTrimPriorityComparison devuelve S_OK. Si el nuevo guión gráfico recorta el guión gráfico programado, el guión gráfico programado ya no puede afectar a una variable cuando el nuevo guión gráfico comienza a animar esa variable.
Concluir el guión gráfico programado si el guión gráfico programado contiene un bucle con un recuento de repeticiones de UI_ANIMATION_REPEAT_INDEFINITELY y el objeto de comparación de prioridad registrado con IUIAnimationManager::SetConcludePriorityComparison devuelve S_OK. Si se concluye el guión gráfico, se completa la repetición actual del bucle y, a continuación, se reproduce el recordatorio del guión gráfico.
Comprima el guión gráfico programado y cualquier otro guión gráfico animando las mismas variables, si el objeto de comparación de prioridad registrado con IUIAnimationManager::SetCompressPriorityComparison devuelve S_OK para todos los guiones gráficos programados que podrían verse afectados por la compresión. Cuando se comprimen los guiones gráficos, el tiempo se acelera temporalmente para guiones gráficos afectados, por lo que juegan más rápido.

Si ninguno de los objetos de comparación de prioridad permite ninguna de las opciones anteriores, se produce un error en el intento de programar el guión gráfico y la animación de Windows devuelve UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY a la aplicación que realiza la llamada.

Tenga en cuenta que, para que el nuevo guión gráfico se programe correctamente, debe comenzar antes de que haya transcurrido su retraso aceptable más largo. Esto viene determinado por IUIAnimationStoryboard::SetLongestAcceptableDelay o IUIAnimationManager::SetDefaultLongestAcceptableDelay (si no se llama a ninguno, el valor predeterminado es 0,0 segundos). Si el retraso más largo aceptable es UI_ANIMATION_SECONDS_EVENTUALLY, cualquier retraso finito será suficiente.

El parámetro priorityEffect describe el posible efecto en el nuevo guión gráfico si HasPriority devolvía S_FALSE. Si priorityEffect es UI_ANIMATION_PRIORITY_EFFECT_FAILURE, es posible que la devolución de S_FALSE produzca un error al programar el nuevo guión gráfico (también es posible que el administrador de animaciones pueda resolver el conflicto de una manera diferente mediante otro objeto de comparación de prioridad). Si priorityEffect es UI_ANIMATION_PRIORITY_EFFECT_DELAY, el único inconveniente de devolver S_FALSE es que el guión gráfico podría comenzar más adelante de lo que habría devuelto HasPriority S_OK.

Cuando se pasa UI_ANIMATION_PRIORITY_EFFECT_DELAY a HasPriority, el administrador de animaciones ya ha determinado que puede programar el nuevo guión gráfico para que comience antes de que haya transcurrido su retraso aceptable más largo, pero está en vigor preguntando a la aplicación si el guión gráfico debe comenzar incluso antes. En algunos escenarios, puede ser mejor reducir la latencia de una animación devolviendo S_OK. En otros, puede ser preferible permitir que las animaciones programadas se completen siempre que sea posible, en cuyo caso se debe devolver S_FALSE. UI_ANIMATION_PRIORITY_EFFECT_DELAY solo se pasa a HasPriority cuando el administrador de animaciones está considerando cancelar o recortar un guión gráfico.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7, Windows Vista y Actualización de plataforma para Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	No se admite ninguno
Plataforma de destino	Windows
Encabezado	uianimation.h
Archivo DLL	UIAnimation.dll