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

Artigo
08/26/2023

Exibe ou atualiza uma barra de progresso hospedada em um botão da barra de tarefas para mostrar a porcentagem específica concluída da operação completa.

Sintaxe

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

Parâmetros

[in] hwnd

Digite: HWND

O identificador da janela cujo botão da barra de tarefas associado está sendo usado como um indicador de progresso.

[in] ullCompleted

Tipo: ULONGLONG

Um valor definido pelo aplicativo que indica a proporção da operação que foi concluída no momento em que o método é chamado.

[in] ullTotal

Tipo: ULONGLONG

Um valor definido pelo aplicativo que especifica o valor que ullCompleted terá quando a operação for concluída.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Ciclo de vida da barra de progresso determinado

Um aplicativo primeiro chama SetProgressValue para iniciar a exibição de uma barra de progresso determinada e, em seguida, chama-a novamente conforme necessário para atualizar a barra à medida que o progresso muda. Quando o progresso for concluído, o aplicativo deverá chamar SetProgressState com o sinalizador TBPF_NOPROGRESS para ignorar a barra de progresso.

Como o botão da barra de tarefas escolhe o indicador de progresso para um grupo

O botão da barra de tarefas pode mostrar um indicador de progresso para apenas uma janela de cada vez. Quando o botão da barra de tarefas representa um grupo e mais de uma das janelas desse grupo estão transmitindo informações de progresso, o botão da barra de tarefas escolhe sua exibição de progresso com base na prioridade de estado a seguir.

Prioridade	Estado
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

A menos que SetProgressState tenha definido um estado de bloqueio (TBPF_ERROR ou TBPF_PAUSED) para a janela, uma chamada para SetProgressValue pressupõe o estado de TBPF_NORMAL mesmo que ele não esteja definido explicitamente. Uma chamada para SetProgressValue substitui e limpa o estado TBPF_INDETERMINATE.

No caso de uma colisão de prioridade em que duas janelas estão transmitindo o progresso determinado, a janela com o menor progresso é usada.

Com base nessa prioridade, esse indicador de progresso determinado (percentual específico) pode ser exibido nesses casos:

O botão da barra de tarefas não representa um grupo e a única janela que ele representa está transmitindo informações de progresso determinadas por meio desse método.
O botão da barra de tarefas representa um grupo, apenas uma janela nesse grupo está transmitindo informações de progresso e essa janela está transmitindo informações de progresso determinadas por meio desse método.
O botão da barra de tarefas representa um grupo, várias janelas desse grupo estão transmitindo informações de progresso, pelo menos uma dessas janelas está transmitindo informações de progresso por meio desse método e nenhuma dessas janelas definiu o estado TBPF_ERROR ou TBPF_PAUSED .

Se uma janela no grupo tiver definido TBPF_ERROR ou TBPF_PAUSED, esse estado será usado para a exibição do botão. No entanto, você ainda pode fazer chamadas para SetProgressValue em outras janelas desbloqueadas no grupo para atualizar seu progresso em segundo plano.

Exemplos

Aqui está um exemplo de como um aplicativo pode usar ITaskbarList3 para exibir o progresso enquanto está executando operações.

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	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)
Biblioteca	Explorerframe.lib
DLL	Explorerframe.dll