Compartilhar via

função Shell_NotifyIconA (shellapi.h)

  • Artigo

Envia uma mensagem para a área de status da barra de tarefas.

Sintaxe

BOOL Shell_NotifyIconA(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAA lpData
);

Parâmetros

[in] dwMessage

Tipo: DWORD

Um valor que especifica a ação a ser tomada por essa função. Ele pode ter um dos seguintes valores:

NIM_ADD (0x00000000)

0x00000000. Adiciona um ícone à área de status. O ícone recebe um identificador na estrutura de NOTIFYICONDATA apontada por lpdata — por meio de seu uID ou membro guidItem. Esse identificador é usado em chamadas subsequentes para Shell_NotifyIcon para executar ações posteriores no ícone.

NIM_MODIFY (0x00000001)

0x00000001. Modifica um ícone na área de status. a estrutura NOTIFYICONDATA apontada pelo lpdata usa a ID originalmente atribuída ao ícone quando foi adicionada à área de notificação (NIM_ADD) para identificar o ícone a ser modificado.

NIM_DELETE (0x00000002)

0x00000002. Exclui um ícone da área de status. a estrutura NOTIFYICONDATA apontada pelo lpdata usa a ID originalmente atribuída ao ícone quando foi adicionada à área de notificação (NIM_ADD) para identificar o ícone a ser excluído.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll versão 5.0 e posterior apenas. Retorna o foco para a área de notificação da barra de tarefas. Os ícones da área de notificação devem usar essa mensagem quando tiverem concluído a operação de interface do usuário. Por exemplo, se o ícone exibir um menu de atalho, mas o usuário pressionar ESC para cancelá-lo, use NIM_SETFOCUS para retornar o foco para a área de notificação.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll versão 5.0 e posterior apenas. Instrui a área de notificação a se comportar de acordo com o número de versão especificado no uVersion membro da estrutura apontada por lpdata. O número da versão especifica quais membros são reconhecidos.

NIM_SETVERSION deve ser chamado sempre que um ícone de área de notificação é adicionado (NIM_ADD). Ele não precisa ser chamado com NIM_MODIFY. A configuração de versão não é mantida quando um usuário faz logoff.

Para obter detalhes, consulte a seção Comentários.

[in] lpData

Tipo: PNOTIFYICONDATA

Um ponteiro para uma estrutura de NOTIFYICONDATA . O conteúdo da estrutura depende do valor de dwMessage. Ele pode definir um ícone a ser adicionado à área de notificação, fazer com que esse ícone exiba uma notificação ou identifique um ícone para modificar ou excluir.

Valor de retorno

Tipo: BOOL

Retorna TRUE se tiver êxito ou false caso contrário. Se dwMessage estiver definido como NIM_SETVERSION, a função retornará VERDADEIRO se a versão tiver sido alterada com êxito ou FALSE se a versão solicitada não tiver suporte.

Observações

A partir do Windows 2000 (Shell32.dll versão 5.0), se você definir o membro do NOTIFYICONDATA estrutura apontada por lpdata como NOTIFYICON_VERSION_4 ou superior, Shell_NotifyIcon eventos de mouse e teclado são tratados de forma diferente das versões anteriores do Windows. As diferenças incluem o seguinte:

  • Se um usuário selecionar o menu de atalho de um ícone de notificação com o teclado, o Shell enviará ao aplicativo associado uma mensagem WM_CONTEXTMENU. Versões anteriores enviam mensagens WM_RBUTTONDOWN e WM_RBUTTONUP.
  • Se um usuário selecionar um ícone de notificação com o teclado e ativá-lo com a tecla SPACEBAR ou ENTER, o Shell da versão 5.0 enviará ao aplicativo associado uma notificação NIN_KEYSELECT. Versões anteriores enviam mensagens WM_RBUTTONDOWN e WM_RBUTTONUP.
  • Se um usuário selecionar um ícone de notificação com o mouse e ativá-lo com a chave ENTER, o Shell agora enviará ao aplicativo associado uma notificação NIN_SELECT. Versões anteriores enviam mensagens WM_RBUTTONDOWN e WM_RBUTTONUP.
A partir do Windows XP (Shell32.dll versão 6.0), se um usuário passar o ponteiro do mouse sobre um ícone com o qual uma notificação de balão está associada, o Shell enviará as seguintes mensagens:
  • NIN_BALLOONSHOW. Enviado quando o balão é mostrado (balões são enfileirados).
  • NIN_BALLOONHIDE. Enviado quando o balão desaparece. Por exemplo, quando o ícone é excluído. Essa mensagem não será enviada se o balão for descartado devido a um tempo limite ou se o usuário clicar no mouse.

    A partir do Windows 7, NIN_BALLOONHIDE também é enviado quando uma notificação com o sinalizador NIIF_RESPECT_QUIET_TIME tenta exibir durante o tempo de silêncio (a primeira hora de um usuário em um novo computador). Nesse caso, o balão nunca é exibido.

  • NIN_BALLOONTIMEOUT. Enviado quando o balão é descartado por causa de um tempo limite.
  • NIN_BALLOONUSERCLICK. Enviado quando o balão é descartado porque o usuário clicou no mouse.
Além dessas mensagens, a partir do Windows Vista (Shell32.dll versão 6.0.6), se um usuário passar o ponteiro do mouse sobre um ícone com o qual uma notificação de balão está associada, o Shell do Windows Vista também adicionará as seguintes mensagens:
  • NIN_POPUPOPEN. Enviado quando o usuário passa o cursor sobre um ícone para indicar que a interface do usuário pop-up mais avançada deve ser usada no lugar de uma dica de ferramenta textual padrão.
  • NIN_POPUPCLOSE. Enviado quando um cursor não passa mais o mouse sobre um ícone para indicar que a interface do usuário pop-up avançada deve ser fechada.
Independentemente da versão do sistema operacional, você pode selecionar como o Shell deve se comportar chamando Shell_NotifyIcon com dwMessage definido como NIM_SETVERSION. Defina o membro do NOTIFYICONDATA apontado por lpdata para indicar se você deseja o comportamento do Windows 2000, do Windows Vista ou da pré-versão 5.0 (Windows 95).
Observação As mensagens discutidas acima não são mensagens convencionais do Windows. Eles são enviados como o lParam valor da mensagem definida pelo aplicativo especificada no membro uCallbackMessage da estrutura de NOTIFYICONDATA apontada por lpdata, quando Shell_NotifyIcon é chamado com o sinalizador NIM_ADD definido em dwMessage.
 
A partir do Windows XP Service Pack 2 (SP2), um ícone personalizado pode ser exibido no balão de notificação. Isso permite que o processo de chamada personalize a notificação além das opções de informações, aviso e erro disponíveis anteriormente e distingue-a de outros tipos de notificação para o usuário.

Nota

O cabeçalho shellapi.h define Shell_NotifyIcon como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho shellapi.h
biblioteca Shell32.lib
de DLL Shell32.dll (versão 4.0 ou posterior)
conjunto de API ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)

Consulte também

Notificações e a área de notificação