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

Artículo
08/26/2023

Muestra o actualiza una barra de progreso hospedada en un botón de barra de tareas para mostrar el porcentaje específico completado de la operación completa.

Sintaxis

HRESULT SetProgressValue(
  [in] HWND      hwnd,
  [in] ULONGLONG ullCompleted,
  [in] ULONGLONG ullTotal
);

Parámetros

[in] hwnd

Tipo: HWND

Identificador de la ventana cuyo botón de barra de tareas asociado se usa como indicador de progreso.

[in] ullCompleted

Tipo: ULONGLONG

Valor definido por la aplicación que indica la proporción de la operación que se ha completado en el momento en que se llama al método .

[in] ullTotal

Tipo: ULONGLONG

Un valor definido por la aplicación que especifica el valor ullCompleted tendrá cuando se complete la operación.

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

Ciclo de vida de la barra de progreso determinado

Una aplicación llama primero a SetProgressValue para comenzar la presentación de una barra de progreso determinada y, a continuación, la llama de nuevo según sea necesario para actualizar la barra a medida que cambia el progreso. Una vez completado el progreso, la aplicación debe llamar a SetProgressState con la marca TBPF_NOPROGRESS para descartar la barra de progreso.

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. Cuando el botón de la barra de tareas representa un grupo y más de una de las ventanas de ese grupo están transmitiendo información de progreso, el botón de la barra de tareas elige su presentación de progreso en función de la siguiente prioridad de estado.

Priority	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

A menos que SetProgressState haya establecido un estado de bloqueo (TBPF_ERROR o TBPF_PAUSED) para la ventana, una llamada a SetProgressValue asume el estado de TBPF_NORMAL aunque no esté establecido explícitamente. Una llamada a SetProgressValue invalida y borra el estado TBPF_INDETERMINATE.

En el caso de una colisión de prioridad en la que dos ventanas están emitiendo un progreso determinado, se usa la ventana con el menor progreso.

En función de esa prioridad, este indicador de progreso determinado (porcentaje específico) se puede mostrar en estos casos:

El botón de la barra de tareas no representa un grupo y la única ventana que representa es la difusión de información de progreso determinada a través de este método.
El botón de la barra de tareas representa un grupo, solo una ventana de ese grupo es la difusión de información de progreso y esa ventana transmite información de progreso determinada a través de este método.
El botón de la barra de tareas representa un grupo, varias ventanas de ese grupo están transmitiendo información de progreso, al menos una de esas ventanas está difundiendo información de progreso a través de este método y ninguna de esas ventanas ha establecido el estado TBPF_ERROR o TBPF_PAUSED .

Si una ventana del grupo ha establecido TBPF_ERROR o TBPF_PAUSED, ese estado se usará para la presentación del botón. Sin embargo, todavía puede realizar llamadas a SetProgressValue en otras ventanas desbloqueadas del grupo para actualizar su progreso en segundo plano.

Ejemplos

Este es un ejemplo de cómo una aplicación podría usar ITaskbarList3 para mostrar el progreso mientras realiza operaciones.

HRESULT CMyApp::ShowProgressInTaskbar(HWND hwnd, __in ITaskbarList3 *pTL)
{
    // Set the progress state of the button to indeterminate while you calculate
    // the number of operations to be performed.
    HRESULT hr = pTL->SetProgressState(hwnd, TBPF_INDETERMINATE);

    // Calculate the number of operations to perform.
    int cTotalOperations = _CalculateNumberOfOperationsToPerform();

    for (int i=0; i < cTotalOperations && SUCCEEDED(hr); i++)
    {
        // Update the progress. This call to SetProgressValue cancels the
        // indeterminate state and puts the button into normal progress mode.
        pTL->SetProgressValue(hwnd, i, cTotalOperations);
       
        // Do whatever operation your application needs to perform.
        hr = _PerformOperation(i);
    }

    // Tell the button that progress no longer needs to be displayed.
    pTL->SetProgressState(hwnd, TBPF_NOPROGRESS);
    
    return hr;
}

Requisitos

Requisito	Value
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 (incluya Shobjidl.h)
Library	Explorerframe.lib
Archivo DLL	Explorerframe.dll