Método ITaskbarList3::SetProgressState (shobjidl_core.h)

Artículo
08/26/2023

Establece el tipo y el estado del indicador de progreso mostrado en un botón de la barra de tareas.

Sintaxis

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

Parámetros

[in] hwnd

Tipo: HWND

Identificador de la ventana en la que se muestra el progreso de una operación. El botón de la barra de tareas asociada de esta ventana mostrará la barra de progreso.

[in] tbpFlags

Tipo: TBPFLAG

Marcas que controlan el estado actual del botón de progreso. Especifique solo una de las marcas siguientes; todos los estados son mutuamente excluyentes de todos los demás.

TBPF_NOPROGRESS (0x00000000)

Deja de mostrar el progreso y devuelve el botón a su estado normal. Llame a este método con esta marca para descartar la barra de progreso cuando se complete o cancele la operación.

TBPF_INDETERMINATE (0x00000001)

El indicador de progreso no crece en tamaño, pero recorre repetidamente la longitud del botón de la barra de tareas. Esto indica la actividad sin especificar qué proporción del progreso se ha completado. El progreso se está llevando a cabo, pero no hay ninguna predicción sobre cuánto tiempo tardará la operación.

TBPF_NORMAL (0x00000002)

El indicador de progreso aumenta de tamaño de izquierda a derecha en proporción a la cantidad estimada de la operación completada. Se trata de un indicador de progreso determinado; se realiza una predicción en cuanto a la duración de la operación.

TBPF_ERROR (0x00000004)

El indicador de progreso se vuelve rojo para mostrar que se ha producido un error en una de las ventanas que está difundiendo el progreso. Se trata de un estado determinado. Si el indicador de progreso está en estado indeterminado, cambia a una presentación determinada roja de un porcentaje genérico no indicativo del progreso real.

TBPF_PAUSED (0x00000008)

El indicador de progreso se vuelve amarillo para mostrar que el progreso está detenido actualmente en una de las ventanas, pero el usuario puede reanudarlo. No existe ninguna condición de error y nada impide que el progreso continúe. Se trata de un estado determinado. Si el indicador de progreso está en el estado indeterminado, cambia a una presentación determinación amarilla de un porcentaje genérico no indicativo del progreso real.

Valor devuelto

Tipo: HRESULT

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

La información de la barra de progreso no se muestra en combinaciones de colores de contraste alto para garantizar que no se vean comprometidas las necesidades de accesibilidad.

Los desarrolladores acostumbrados al control de barra de progreso existente deben encontrar el indicador de progreso del botón de la barra de tareas para ser una experiencia similar tanto en el concepto como en los objetos visuales. Aquí, el propio botón de la barra de tareas se convierte en una barra de progreso. El indicador de progreso de un botón de la barra de tareas debe ser un reflejo de una barra de progreso más detallada en la ventana asociada. Esto permite al usuario ver detalles, como el número de porcentaje y la cantidad de tiempo restante, que no se pueden mostrar en un botón de la barra de tareas. Además, dado que un botón de la barra de tareas puede mostrar el progreso de una sola ventana de un grupo, permite al usuario comprobar el progreso de las ventanas individuales. También proporciona información de progreso al usuario cuando el botón de la barra de tareas no puede, como en una combinación de colores de contraste alto.

Tenga en cuenta que una barra de progreso del botón de la barra de tareas no está pensada para usarse con acciones periféricas normales, como la carga de una página web o la impresión de un documento. Ese tipo de progreso debe seguir mostrándose en la barra de estado de una ventana.

El indicador de progreso se muestra entre el icono o el texto del botón de la barra de tareas y el fondo. Si se muestra el progreso tanto para el botón de la barra de tareas activa como para un botón inactivo, sombreado en las barras de progreso respectivas es tal que el botón activo sigue siendo obvio para el usuario. Además, la funcionalidad de botón, como la presentación de miniaturas, sigue funcionando normalmente cuando se usa el botón para mostrar el progreso.

Al salir de un estado de error o pausado, vuelva a llamar a este método con la marca TBPF_NORMAL o TBPF_INDETERMINATE para continuar en el estado original o TBPF_NOPROGRESS si se cancela la operación.

Cómo elige el botón barra de tareas el indicador de progreso de un grupo

El botón de la barra de tareas puede mostrar un indicador de progreso solo para una ventana a la vez. Esto incluye la situación en la que el botón de la barra de tareas representa un grupo y más de una ventana de ese grupo está difundiendo información de progreso. En ese caso, el botón de la barra de tareas elige su presentación de progreso en función de la prioridad de estado. La prioridad de estado se muestra en la tabla siguiente con la prioridad 1, siendo la más alta.

Priority	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Cambiar el estado de una ventana cambia su prioridad en relación con otras ventanas del grupo que, a su vez, podría cambiar qué ventana de un grupo se usa para el indicador de progreso en el botón de la barra de tareas.

En el caso de una colisión de prioridad entre dos ventanas que difunden el progreso determinado, se usa la ventana con el menor progreso.

En función de esta prioridad, el indicador de progreso indeterminado solo se puede mostrar en el botón de la barra de tareas en estos casos:

El botón de la barra de tareas no representa un grupo y la ventana única que representa ha establecido TBPF_INDETERMINATE.
El botón de la barra de tareas representa un grupo, solo una ventana de ese grupo está difundiendo información de progreso y esa ventana ha establecido TBPF_INDETERMINATE.
El botón de la barra de tareas representa un grupo, varias ventanas de ese grupo están difundiendo información de progreso y todas esas ventanas han establecido TBPF_INDETERMINATE.

En estos casos se puede mostrar un indicador de progreso determinado:

El botón de la barra de tareas no representa un grupo y la única ventana que representa está difundiendo información de progreso determinada.
El botón de la barra de tareas representa un grupo, solo una ventana de ese grupo está difundiendo información de progreso y esa ventana está difundiendo información de progreso determinada.
El botón de la barra de tareas representa un grupo, varias ventanas de ese grupo están difundiendo información de progreso, al menos una de esas ventanas está difundiendo información de progreso determinada y ninguna ventana ha establecido TBPF_ERROR o TBPF_PAUSED.

Tenga en cuenta que una llamada a SetProgressValue cambiará un indicador de progreso actualmente en un modo indeterminado (TBPF_INDETERMINATE) a una pantalla normal (determinada) y borrará la marca TBPF_INDETERMINATE .

Requisitos


Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shobjidl_core.h (include Shobjidl.h)
Library	Explorerframe.lib
Archivo DLL	Explorerframe.dll