Função Shell_NotifyIconA (shellapi.h)
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 executada por essa função. Pode ter um dos seguintes valores:
NIM_ADD (0x00000000)
0x00000000. Adiciona um ícone à área status. O ícone recebe um identificador na estrutura NOTIFYICONDATA apontada por lpdata, seja por meio de seu membro uID ou 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 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 somente. 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 somente. Instrui a área de notificação a se comportar de acordo com o número de versão especificado no membro uVersion da estrutura apontada por lpdata. O número de 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 é persistida depois que um usuário faz logoff.
Para obter detalhes, consulte a seção Comentários.
[in] lpData
Tipo: PNOTIFYICONDATA
Um ponteiro para uma estrutura NOTIFYICONDATA . O conteúdo da estrutura depende do valor de dwMessage. Ele pode definir um ícone para adicionar à área de notificação, fazer com que esse ícone exiba uma notificação ou identifique um ícone para modificar ou excluir.
Retornar valor
Tipo: BOOL
Retornará TRUE se tiver êxito ou FALSE caso contrário. Se dwMessage estiver definido como NIM_SETVERSION, a função retornará TRUE se a versão tiver sido alterada com êxito ou FALSE se não houver suporte para a versão solicitada.
Comentários
A partir do Windows 2000 (Shell32.dll versão 5.0), se você definir o membro uVersion da estrutura NOTIFYICONDATA apontada por lpdata para NOTIFYICON_VERSION_4 ou superior, Shell_NotifyIcon eventos de mouse e teclado são manipulados de forma diferente do que nas 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 agora 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 de 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 tecla ENTER, o Shell agora enviará ao aplicativo associado uma notificação NIN_SELECT. Versões anteriores enviam mensagens WM_RBUTTONDOWN e WM_RBUTTONUP .
- 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. Esta 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 de sinalizadores 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 devido a um tempo limite.
- NIN_BALLOONUSERCLICK. Enviado quando o balão é ignorado porque o usuário clicou no mouse.
- NIN_POPUPOPEN. Enviado quando o usuário passa o cursor sobre um ícone para indicar que a interface do usuário pop-up mais rica 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.
Observação
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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | shellapi.h |
| Biblioteca | Shell32.lib |
| DLL | Shell32.dll (versão 4.0 ou posterior) |
| Conjunto de APIs | ext-ms-win-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240) |