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

Artículo
08/26/2023

Determina la prioridad relativa entre un guión gráfico programado y un nuevo guión gráfico.

Sintaxis

HRESULT HasPriority(
  [in] IUIAnimationStoryboard2      *scheduledStoryboard,
  [in] IUIAnimationStoryboard2      *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 interrumpe el guión gráfico programado especificado por scheduledStoryboard.

[in] priorityEffect

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

Valor devuelto

Devuelve lo siguiente si se ejecuta correctamente; de lo contrario, un código de error HRESULT . Consulta Códigos de error de animación de Windows para obtener una lista de códigos de error.

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 al método 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 IUIAnimationManager2::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 IUIAnimationManager2::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.
Concluye 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 IUIAnimationManager2::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 IUIAnimationManager2::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 IUIAnimationManager2::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 tendría si HasPriority hubiera devuelto S_OK.

Cuando UI_ANIMATION_PRIORITY_EFFECT_DELAY se pasa a HasPriority, el administrador de animaciones ya ha determinado que puede programar el nuevo guión gráfico para comenzar 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 HasPriority 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 8, Windows 7 y Actualización de plataforma para Windows 7 [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