Estrutura NOTIFYICONDATAA (shellapi.h)
Contém informações de que o sistema precisa exibir notificações na área de notificação. Usado por Shell_NotifyIcon.
Sintaxe
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
Membros
cbSize
Tipo: DWORD
O tamanho dessa estrutura, em bytes.
hWnd
Tipo: HWND
Um identificador para a janela que recebe notificações associadas a um ícone na área de notificação.
uID
Tipo: UINT
O identificador definido pelo aplicativo do ícone da barra de tarefas. O Shell usa (hWnd mais uID ) ou guidItem para identificar em qual ícone operar quando Shell_NotifyIcon é invocado. Você pode ter vários ícones associados a um único hWnd atribuindo a cada um um uID diferente. Se guidItem for especificado, uID será ignorado.
uFlags
Tipo: UINT
Sinalizadores que indicam quais dos outros membros da estrutura contêm dados válidos ou fornecem informações adicionais à dica de ferramenta sobre como ela deve ser exibida. Esse membro pode ser uma combinação dos seguintes valores:
NIF_MESSAGE (0x00000001)
0x00000001. O membro
NIF_ICON (0x00000002)
0x00000002. O membro hIcon é válido.
NIF_TIP (0x00000004)
0x00000004. O membro szTip é válido.
NIF_STATE (0x00000008)
0x00000008. Os membros dwState
NIF_INFO (0x00000010)
0x00000010. Exibir uma notificação de balão. Os membros szInfo, szInfoTitle, dwInfoFlagse uTimeout são válidos. Observe que uTimeout é válido apenas no Windows 2000 e no Windows XP.
- Para exibir a notificação de balão, especifique NIF_INFO e forneça texto em szInfo.
- Para remover uma notificação de balão, especifique NIF_INFO e forneça uma cadeia de caracteres vazia por szInfo.
- Para adicionar um ícone de área de notificação sem exibir uma notificação, não defina o sinalizador NIF_INFO.
NIF_GUID (0x00000020)
0x00000020.
- Windows 7 e posteriores: o guidItem é válido.
- Windows Vista eanteriores: Reservado.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista e posteriores. Se a notificação de balão não puder ser exibida imediatamente, descarte-a. Use esse sinalizador para notificações que representam informações em tempo real que seriam sem sentido ou enganosas se exibidas posteriormente. Por exemplo, uma mensagem informando "Seu telefone está tocando". NIF_REALTIME só é significativo quando combinado com o sinalizador NIF_INFO.
NIF_SHOWTIP (0x00000080)
0x00000080. Windows Vista e posteriores. Use a dica de ferramenta padrão. Normalmente, quando uVersion é definido como NOTIFYICON_VERSION_4, a dica de ferramenta padrão é suprimida e pode ser substituída pela interface do usuário pop-up desenhada pelo aplicativo. Se o aplicativo quiser mostrar a dica de ferramenta padrão com NOTIFYICON_VERSION_4, ele poderá especificar NIF_SHOWTIP para indicar que a dica de ferramenta padrão ainda deve ser mostrada.
uCallbackMessage
Tipo: UINT
Um identificador de mensagem definido pelo aplicativo. O sistema usa esse identificador para enviar mensagens de notificação para a janela identificada em hWnd. Essas mensagens de notificação são enviadas quando um evento ou foco do mouse ocorre no retângulo delimitador do ícone, quando o ícone é selecionado ou ativado com o teclado ou quando essas ações ocorrem na notificação de balão.
Quando o membro
Quando o membro
- LOWORD(lParam) contém eventos de notificação, como NIN_BALLOONSHOW, NIN_POPUPOPEN ou WM_CONTEXTMENU.
- HIWORD(lParam) contém a ID do ícone. As IDs de ícone são restritas a um comprimento de 16 bits.
- GET_X_LPARAM(wParam) retorna a coordenada de âncora X para eventos de notificação NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT e todas as mensagens do mouse entre WM_MOUSEFIRST e WM_MOUSELAST. Se qualquer uma dessas mensagens for gerada pelo teclado, wParam será definido como o canto superior esquerdo do ícone de destino. Para todas as outras mensagens, wParam é indefinido.
- GET_Y_LPARAM(wParam) retorna a coordenada de âncora Y para eventos de notificação e mensagens, conforme definido para a âncora X.
hIcon
Tipo: HICON
Um identificador para o ícone a ser adicionado, modificado ou excluído. O Windows XP e posteriores dão suporte a ícones de até 32 BPP.
Se apenas um ícone de 16 x 16 pixels for fornecido, ele será dimensionado para um tamanho maior em um sistema definido como um valor dpi alto. Isso pode levar a um resultado pouco atraente. É recomendável que você forneça um ícone de 16 x 16 pixels e um ícone 32x32 no arquivo de recurso. Use LoadIconMetric para garantir que o ícone correto seja carregado e dimensionado adequadamente. Consulte Comentários para obter um exemplo de código.
szTip[64]
Tipo: TCHAR[64]
Uma cadeia de caracteres terminada em nulo que especifica o texto para uma dica de ferramenta padrão. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de encerramento.
Para o Windows 2000 e posterior, szTip pode ter no máximo 128 caracteres, incluindo o caractere nulo de terminação.
szTip[128]
Tipo: TCHAR[64]
Uma cadeia de caracteres terminada em nulo que especifica o texto para uma dica de ferramenta padrão. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de encerramento.
Para o Windows 2000 e posterior, szTip pode ter no máximo 128 caracteres, incluindo o caractere nulo de terminação.
dwState
Tipo: DWORD
Windows 2000 e posteriores. O estado do ícone. Um ou ambos os seguintes valores:
NIS_HIDDEN (0x00000001)
0x00000001. O ícone está oculto.
NIS_SHAREDICON (0x00000002)
0x00000002. O recurso de ícone é compartilhado entre vários ícones.
dwStateMask
Tipo: DWORD
Windows 2000 e posteriores. Um valor que especifica quais bits do membro
szInfo[256]
Tipo: TCHAR[256]
Windows 2000 e posteriores. Uma cadeia de caracteres terminada em nulo que especifica o texto a ser exibido em uma notificação de balão. Ele pode ter no máximo 256 caracteres, incluindo o caractere nulo de encerramento, mas deve ser restrito a 200 caracteres em inglês para acomodar a localização. Para remover a notificação de balão da interface do usuário, exclua o ícone (com NIM_DELETE) ou defina o sinalizador NIF_INFO em uFlags e defina szInfo como uma cadeia de caracteres vazia.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
Tipo: UINT
Windows 2000 e posteriores.
DUMMYUNIONNAME.uVersion
Tipo: UINT
Windows 2000 e posteriores. União com uTimeout (preterido a partir do Windows Vista). Especifica qual versão da interface de ícone de notificação do Shell deve ser usada. Para obter mais informações sobre as diferenças nessas versões, consulte Shell_NotifyIcon. Esse membro é empregado somente ao usar Shell_NotifyIcon para enviar uma mensagem de NIM_SETVERSION.
szInfoTitle[64]
Tipo: TCHAR[64]
Windows 2000 e posteriores. Uma cadeia de caracteres terminada em nulo que especifica um título para uma notificação de balão. Esse título aparece em uma fonte maior imediatamente acima do texto. Ele pode ter no máximo 64 caracteres, incluindo o caractere nulo de encerramento, mas deve ser restrito a 48 caracteres em inglês para acomodar a localização.
dwInfoFlags
Tipo: DWORD
Windows 2000 e posteriores. Sinalizadores que podem ser definidos para modificar o comportamento e a aparência de uma notificação de balão. O ícone é colocado à esquerda do título. Se o membro szInfoTitle for de comprimento zero, o ícone não será mostrado.
NIIF_NONE (0x00000000)
0x00000000. Nenhum ícone.
NIIF_INFO (0x00000001)
0x00000001. Um ícone de informações.
NIIF_WARNING (0x00000002)
0x00000002. Um ícone de aviso.
NIIF_ERROR (0x00000003)
0x00000003. Um ícone de erro.
NIIF_USER (0x00000004)
0x00000004. Windows XP SP2 e posterior.
- do Windows XP: use o ícone identificado em hIcon como o ícone de título do balão de notificação.
- Windows Vista e posteriores: use o ícone identificado em hBalloonIcon como o ícone de título do balão de notificação.
NIIF_NOSOUND (0x00000010)
0x00000010. Windows XP e posteriores. Não toque o som associado. Aplica-se somente a notificações.
NIIF_LARGE_ICON (0x00000020)
0x00000020. Windows Vista e posteriores. A versão grande do ícone deve ser usada como o ícone de notificação. Isso corresponde ao ícone com dimensões SM_CXICON x SM_CYICON. Se esse sinalizador não estiver definido, o ícone com dimensões SM_CXSMICON x SM_CYSMICON será usado.
- Esse sinalizador pode ser usado com todos os ícones de estoque .
- Os aplicativos que usam ícones personalizados mais antigos (NIIF_USER com hIcon) devem fornecer uma nova versão SM_CXICON x SM_CYICON no ícone de bandeja (hIcon). Esses ícones são reduzidos verticalmente quando são exibidos na Bandeja do Sistema ou na SCA (Área de Controle do Sistema).
- Novos ícones personalizados (NIIF_USER com hBalloonIcon) devem fornecer uma versão SM_CXICON x SM_CYICON no ícone fornecido (hBalloonIcon).
NIIF_RESPECT_QUIET_TIME (0x00000080)
0x00000080. Windows 7 e posteriores. Não exiba a notificação de balão se o usuário atual estiver em "tempo silencioso", que é a primeira hora após um novo usuário fazer logon em sua conta pela primeira vez. Durante esse tempo, a maioria das notificações não deve ser enviada ou mostrada. Isso permite que um usuário se acostume com um novo sistema de computador sem essas distrações. O tempo de silêncio também ocorre para cada usuário após uma atualização do sistema operacional ou instalação limpa. Uma notificação enviada com esse sinalizador durante o tempo de silêncio não é enfileirada; é simplesmente ignorado sem exibição. O aplicativo poderá reenviar a notificação mais tarde se ainda for válido nesse momento.
Como um aplicativo não pode prever quando pode encontrar um tempo tranquilo, recomendamos que esse sinalizador sempre seja definido em todas as notificações apropriadas por qualquer aplicativo que signifique honrar o tempo de silêncio.
Durante o tempo de silêncio, determinadas notificações ainda devem ser enviadas porque são esperadas pelo usuário como comentários em resposta a uma ação do usuário, por exemplo, quando ele conecta um dispositivo USB ou imprime um documento.
Se o usuário atual não estiver em tempo de silêncio, esse sinalizador não terá efeito.
NIIF_ICON_MASK (0x0000000F)
0x0000000F. Windows XP e posteriores. Reservado.
guidItem
Tipo: guid
Windows XP e posteriores.
-
Windows 7 e posteriores: um GUID registrado que identifica o ícone. Esse valor substitui uID e é o método recomendado para identificar o ícone. O sinalizador NIF_GUID deve ser definido no membro
uFlags. - Windows XP e Windows Vista: Reservado; deve ser definido como 0.
Se você identificar o ícone de notificação com um GUID em uma chamada para Shell_NotifyIcon, deverá usar esse mesmo GUID para identificar o ícone em qualquer Shell_NotifyIcon chamadas subsequentes que lidam com esse mesmo ícone.
Para gerar um GUID para uso neste membro, use uma ferramenta de geração de GUID, como Guidgen.exe.
hBalloonIcon
Tipo: HICON
Windows Vista e posteriores. O identificador de um ícone de notificação personalizado fornecido pelo aplicativo que deve ser usado independentemente do ícone da área de notificação. Se esse membro não for NULL e o sinalizador de NIIF_USER for definido no membro dwInfoFlags
Observações
Consulte "Notificações" nas Diretrizes de Interação da Experiência do Usuário do Windows para obter mais informações sobre a interface do usuário de notificação e as melhores práticas de conteúdo.
Se você definir o sinalizador
Não é possível exibir mais de uma notificação de balão por vez para a barra de tarefas. Se um aplicativo tentar exibir uma notificação quando já estiver sendo exibido, a nova notificação será enfileirada e exibida quando a notificação mais antiga desaparecer. Nas versões do Windows antes do Windows Vista, a nova notificação não seria exibida até que a notificação existente tenha sido visível pelo menos pelo tempo limite mínimo do sistema, independentemente do valor uTimeout da notificação original. Se o usuário não parece estar usando o computador, o sistema não conta esse tempo para o tempo limite.
Há suporte para vários membros dessa estrutura apenas para Windows 2000 e posteriores. Para habilitar esses membros, inclua uma das seguintes linhas em seu cabeçalho:
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
Observe que você deve inicializar a estrutura com seu tamanho. Se você usar o tamanho da estrutura definida no momento, o aplicativo poderá não ser executado com versões anteriores do Shell32.dll, que esperam uma estrutura menor. Você pode executar seu aplicativo em versões anteriores do Shell32.dll definindo o número de versão apropriado (consulte Shell e Common Controls Versions). No entanto, isso poderá causar problemas se o aplicativo também precisar ser executado em sistemas mais recentes.
Você pode manter a compatibilidade do aplicativo com todas as versões Shell32.dll enquanto ainda usa os arquivos de cabeçalho atuais definindo o tamanho da estrutura NOTIFYICONDATA adequadamente. Antes de inicializar a estrutura, use DllGetVersion para determinar qual versão Shell32.dll está instalada no sistema e inicialize cbSize com um destes valores:
| versão do Shell32.dll | cbSize |
|---|---|
| 6.0.6 ou superior (Windows Vista e posterior) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| Versões inferiores a 5.0 | NOTIFYICONDATA_V1_SIZE |
Usar esse valor para cbSize permite que seu aplicativo use NOTIFYICONDATA em um método compatível com versões de Shell32.dll anteriores.
O exemplo de código a seguir mostra a verificação de versão que pode habilitar um aplicativo que usa o guidItem membro para ser executado no Windows Vista e no Windows 7. Ele fornece uma função booliana que retorna VERDADEIRO se o sistema operacional for Windows 7. A menos que esse membro retorne TRUE, o guidItem membro deve ser definido como 0.
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
O exemplo de código a seguir mostra o uso de LoadIconMetric para carregar um ícone para uso com DPI alta.
// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");
// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;
Solução de problemas do
Se você estiver usando o guidItem membro para identificar o ícone e esse ícone não for visto ou algumas chamadas para Shell_NotifyIcon falhar, um dos seguintes casos será a causa provável:- O sinalizador NIF_GUID não foi definido em todas as chamadas para Shell_NotifyIcon. Depois de identificar o ícone de notificação com um GUID em uma chamada para Shell_NotifyIcon, você deve usar esse mesmo GUID para identificar o ícone em qualquer Shell_NotifyIcon chamadas subsequentes que lidam com esse mesmo ícone.
-
O arquivo binário que contém o ícone foi movido. O caminho do arquivo binário é incluído no registro do GUID do ícone e não pode ser alterado. As configurações associadas ao ícone serão preservadas por meio de uma atualização somente se o caminho do arquivo e o GUID não forem alterados. Se o caminho precisar ser alterado, o aplicativo deverá remover todas as informações guid que foram adicionadas quando o ícone existente foi registrado. Depois que essas informações forem removidas, você poderá mover o arquivo binário para um novo local e registrá-lo novamente com um novo GUID. Todas as configurações associadas ao registro guid original serão perdidas.
Isso também ocorre no caso de uma instalação lado a lado. Ao lidar com uma instalação lado a lado, as novas versões do aplicativo devem atualizar o GUID do arquivo binário.
Observação A única exceção a um arquivo movido ocorre quando os arquivos binários originais e movidos são o Authenticodeassinado pela mesma empresa. Nesse caso, as configurações são preservadas por meio da movimentação.
Nota
O cabeçalho shellapi.h define NOTIFYICONDATA 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] |
| cabeçalho | shellapi.h |
Consulte também
Notificações e a área de notificação