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

Artigo
08/26/2023

Define o tipo e o estado do indicador de progresso exibido em um botão da barra de tarefas.

Sintaxe

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

Parâmetros

[in] hwnd

Digite: HWND

O identificador da janela na qual o progresso de uma operação está sendo mostrado. O botão da barra de tarefas associado a essa janela exibirá a barra de progresso.

[in] tbpFlags

Tipo: TBPFLAG

Sinalizadores que controlam o estado atual do botão de progresso. Especifique apenas um dos sinalizadores a seguir; todos os estados são mutuamente exclusivos de todos os outros.

TBPF_NOPROGRESS (0x00000000)

Para de exibir o progresso e retorna o botão para seu estado normal. Chame esse método com esse sinalizador para ignorar a barra de progresso quando a operação for concluída ou cancelada.

TBPF_INDETERMINATE (0x00000001)

O indicador de progresso não cresce em tamanho, mas circula repetidamente ao longo do comprimento do botão da barra de tarefas. Isso indica a atividade sem especificar qual proporção do progresso foi concluída. O progresso está ocorrendo, mas não há previsão de quanto tempo a operação levará.

TBPF_NORMAL (0x00000002)

O indicador de progresso aumenta de tamanho da esquerda para a direita em proporção à quantidade estimada da operação concluída. Esse é um indicador de progresso determinado; uma previsão está sendo feita quanto à duração da operação.

TBPF_ERROR (0x00000004)

O indicador de progresso fica vermelho para mostrar que ocorreu um erro em uma das janelas que está transmitindo o progresso. Esse é um estado determinado. Se o indicador de progresso estiver no estado indeterminado, ele alterna para uma exibição de determinação vermelha de um percentual genérico não indicativo do progresso real.

TBPF_PAUSED (0x00000008)

O indicador de progresso fica amarelo para mostrar que o progresso está parado atualmente em uma das janelas, mas pode ser retomado pelo usuário. Nenhuma condição de erro existe e nada está impedindo que o progresso continue. Esse é um estado determinado. Se o indicador de progresso estiver no estado indeterminado, ele alterna para uma exibição amarela determinada de um percentual genérico não indicativo do progresso real.

Valor retornado

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

As informações da barra de progresso não são mostradas em esquemas de cores de alto contraste para garantir que nenhuma necessidade de acessibilidade seja comprometida.

Os desenvolvedores acostumados com o controle de barra de progresso existente devem encontrar o indicador de progresso do botão da barra de tarefas como uma experiência semelhante tanto em conceito quanto em visuais. Aqui, o próprio botão da barra de tarefas se torna uma barra de progresso. O indicador de progresso de um botão da barra de tarefas deve ser um reflexo de uma barra de progresso mais detalhada na janela associada. Isso permite que o usuário veja detalhes, como o número percentual e a quantidade de tempo restante, que não podem ser mostrados em um botão da barra de tarefas. Além disso, como um botão da barra de tarefas pode mostrar o progresso de apenas uma única janela em um grupo, ele permite que o usuário marcar o progresso de janelas individuais. Ele também fornece informações de progresso para o usuário quando o botão da barra de tarefas não pode, como em um esquema de cores de alto contraste.

Observe que uma barra de progresso do botão da barra de tarefas não se destina ao uso com ações normalmente periféricas, como o carregamento de uma página da Web ou a impressão de um documento. Esse tipo de progresso deve continuar a ser mostrado na barra de status de uma janela.

O indicador de progresso é exibido entre o ícone ou o texto do botão da barra de tarefas e a tela de fundo. Se o progresso for mostrado para o botão da barra de tarefas ativa e um botão inativo, o sombreamento nas respectivas barras de progresso será de modo que o botão ativo ainda seja óbvio para o usuário. Além disso, a funcionalidade de botão, como a exibição de miniaturas, continua funcionando normalmente quando o botão está sendo usado para exibir o progresso.

Ao sair de um estado de erro ou pausado, chame esse método novamente com o sinalizador TBPF_NORMAL ou TBPF_INDETERMINATE para continuar no estado original ou TBPF_NOPROGRESS se a operação for cancelada.

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. Isso inclui a situação em que o botão da barra de tarefas representa um grupo e mais de uma janela nesse grupo está transmitindo informações de progresso. Nesse caso, o botão da barra de tarefas escolhe sua exibição de progresso com base na prioridade de estado. A prioridade de estado é mostrada na tabela a seguir, com a prioridade 1 sendo a mais alta.

Prioridade	Estado
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Alterar o estado de uma janela altera sua prioridade em relação a outras janelas no grupo que, por sua vez, podem alterar qual janela em um grupo é usada para o indicador de progresso no botão da barra de tarefas.

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

Com base nessa prioridade, o indicador de progresso indeterminado só pode ser exibido no botão da barra de tarefas nesses casos:

O botão da barra de tarefas não representa um grupo e a única janela que ele representa definiu TBPF_INDETERMINATE.
O botão da barra de tarefas representa um grupo, apenas uma janela nesse grupo está transmitindo informações de progresso e essa janela definiu TBPF_INDETERMINATE.
O botão da barra de tarefas representa um grupo, várias janelas desse grupo estão transmitindo informações de progresso e todas essas janelas definiram TBPF_INDETERMINATE.

Um indicador de progresso determinado pode ser exibido nesses casos:

O botão da barra de tarefas não representa um grupo e a única janela que ele representa é transmitir informações de progresso determinadas.
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.
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 determinadas e nenhuma janela definiu TBPF_ERROR ou TBPF_PAUSED.

Observe que uma chamada para SetProgressValue alternará um indicador de progresso atualmente em um modo indeterminado (TBPF_INDETERMINATE) para uma exibição normal (determinante) e limpará o sinalizador TBPF_INDETERMINATE .

Requisitos


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