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

Aplica uma sobreposição a um botão da barra de tarefas para indicar o status do aplicativo ou uma notificação ao usuário.

Sintaxe

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

Parâmetros

[in] hwnd

Digite: HWND

O identificador da janela cujo botão da barra de tarefas associado recebe a sobreposição. Esse identificador deve pertencer a um processo de chamada associado ao aplicativo do botão e deve ser um HWND válido ou a chamada é ignorada.

[in] hIcon

Tipo: HICON

O identificador de um ícone a ser usado como sobreposição. Esse deve ser um ícone pequeno, medindo 16 x 16 pixels a 96 dpi. Se um ícone de sobreposição já estiver aplicado ao botão da barra de tarefas, essa sobreposição existente será substituída.

Esse valor pode ser NULL. A maneira como um valor NULL é tratado depende se o botão da barra de tarefas representa uma única janela ou um grupo de janelas.

• Se o botão da barra de tarefas representar uma única janela, o ícone de sobreposição será removido da exibição.
• Se o botão da barra de tarefas representar um grupo de janelas e uma sobreposição anterior ainda estiver disponível (recebido anteriormente à sobreposição atual, mas ainda não liberado por um valor NULL ), essa sobreposição anterior será exibida no lugar da sobreposição atual.

É responsabilidade do aplicativo de chamada liberar o hIcon quando ele não for mais necessário. Isso geralmente pode ser feito depois que você chama SetOverlayIcon porque a barra de tarefas faz e usa sua própria cópia do ícone.

[in] pszDescription

Tipo: LPCWSTR

Um ponteiro para uma cadeia de caracteres que fornece uma versão de texto alt das informações transmitidas pela sobreposição, para fins de acessibilidade.

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

Em versões do Windows anteriores ao Windows 7, os aplicativos geralmente usavam ícones na área de notificação da barra de tarefas para exibir status de aplicativos e notificações ao usuário. A barra de tarefas do Windows 7 permite que um aplicativo forneça esse mesmo tipo de comentários do usuário por meio do botão da barra de tarefas, centralizando mais informações do aplicativo em um só lugar. Essas sobreposições são semelhantes às sobreposições existentes usadas para ícones de atalho ou notificações de segurança, exibidas no canto inferior direito do botão.

A ilustração a seguir mostra uma sobreposição (o quadrado pequeno e verde que indica o usuário status como "Disponível") aplicado ao botão da barra de tarefas de extrema direita.

sobreposições de Ícone de status Disponíveis servem como uma notificação contextual de status e se destinam a negar a necessidade de uma área de notificação separada status ícone para comunicar essas informações ao usuário. O designer de aplicativos deve decidir durante o ciclo de desenvolvimento qual método – ícone sobreposição ou área de notificação status ícone – melhor atende a esse aplicativo. Os ícones de sobreposição destinam-se a fornecer status ou notificações importantes e de longa data, como status de rede, status de mensagens ou novos emails. Eles não devem ser alterados com frequência, nem devem ser animados.

Para exibir um ícone de sobreposição, a barra de tarefas deve estar no modo de ícone grande padrão. Se a barra de tarefas estiver configurada por meio da Barra de Tarefas e das Propriedades do Menu Iniciar para mostrar ícones pequenos, as sobreposições não poderão ser aplicadas e as chamadas a esse método serão ignoradas.

Como uma única sobreposição é aplicada ao botão da barra de tarefas em vez de às miniaturas de janela individuais, esse é um recurso por grupo em vez de por janela. As solicitações de ícones de sobreposição podem ser recebidas de janelas individuais em um grupo de barras de tarefas, mas não fazem fila. A última sobreposição recebida é a sobreposição mostrada. Se a última sobreposição recebida for removida, a sobreposição substituída será restaurada desde que ainda esteja ativa. Por exemplo, as janelas 1, 2 e 3 definem, em ordem, sobreposições A, B e C. Como a sobreposição C foi recebida por último, ela é mostrada no botão da barra de tarefas. A Janela 2 chama SetOverlayIcon com um valor NULL para remover a sobreposição B. A Janela 3 faz o mesmo para remover a sobreposição C. Como a sobreposição A da janela 1 ainda está ativa, essa sobreposição é exibida no botão da barra de tarefas.

Se o Windows Explorer desligado inesperadamente, as sobreposições não serão restauradas quando o Windows Explorer for restaurado. O aplicativo deve aguardar para receber a mensagem TaskbarButtonCreated que indica que o Windows Explorer foi reiniciado e o botão da barra de tarefas foi recriado e, em seguida, chamar SetOverlayIcon novamente para reaplicar a sobreposição.

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

Confira também

ITaskbarList

ITaskbarList2

Itaskbarlist3

Extensões da barra de tarefas