Поделиться через

Структура NOTIFYICONDATAA (shellapi.h)

  • Статья

Содержит сведения, необходимые системе для отображения уведомлений в области уведомлений. Используется Shell_NotifyIcon.

Синтаксис

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;

Члены

cbSize

Тип: DWORD

Размер этой структуры в байтах.

hWnd

Тип: HWND

Дескриптор окна, получающего уведомления, связанные с значком в области уведомлений.

uID

Тип: UINT

Определяемый приложением идентификатор значка панели задач. Оболочка использует либо (hWnd плюс uID) или guidItem, чтобы определить, какой значок будет работать при вызове Shell_NotifyIcon. Вы можете иметь несколько значков, связанных с одним hWnd, назначив каждому другому uID. Если указан guidItem, uID игнорируется.

uFlags

Тип: UINT

Флаги, указывающие, какие из других элементов структуры содержат допустимые данные или предоставляют дополнительные сведения подсказке о том, как он должен отображаться. Этот элемент может быть сочетанием следующих значений:

NIF_MESSAGE (0x00000001)

0x00000001. Допустимый элемент uCallbackMessage.

NIF_ICON (0x00000002)

0x00000002. Допустимый элемент hIcon.

NIF_TIP (0x00000004)

0x00000004. Допустимый элемент szTip.

NIF_STATE (0x00000008)

0x00000008. Допустимые члены dwState и dwStateMa sk.

NIF_INFO (0x00000010)

0x00000010. Отображение уведомления о воздушных шарах. Допустимы szInfo, szInfoTitle, dwInfoFlagsи элементов uTimeout. Обратите внимание, что uTimeout действительна только в Windows 2000 и Windows XP.

  • Чтобы отобразить уведомление о воздушных шарах, укажите NIF_INFO и укажите текст в szInfo.
  • Чтобы удалить всплывающее уведомление, укажите NIF_INFO и укажите пустую строку через szInfo.
  • Чтобы добавить значок области уведомлений без отображения уведомления, не устанавливайте флаг NIF_INFO.

NIF_GUID (0x00000020)

0x00000020.

  • Windows 7 и более поздних версий: допустимый guidItem .
  • Windows Vista и более ранних: зарезервировано.

NIF_REALTIME (0x00000040)

0x00000040. Windows Vista и более поздних версий. Если уведомление о воздушных шарах не может отображаться немедленно, удалите его. Используйте этот флаг для уведомлений, представляющих информацию в режиме реального времени, которая будет бессмысленной или вводящей в заблуждение при отображении в дальнейшем. Например, сообщение с сообщением "Ваш телефон звонит". NIF_REALTIME имеет смысл только в сочетании с флагом NIF_INFO.

NIF_SHOWTIP (0x00000080)

0x00000080. Windows Vista и более поздних версий. Используйте стандартную подсказку. Как правило, при uVersion задано значение NOTIFYICON_VERSION_4, стандартная подсказка подавляется и может быть заменена нарисованным приложением всплывающий пользовательский интерфейс. Если приложение хочет отобразить стандартную подсказку с NOTIFYICON_VERSION_4, оно может указать NIF_SHOWTIP, чтобы указать стандартную подсказку по-прежнему.

uCallbackMessage

Тип: UINT

Идентификатор сообщения, определяемый приложением. Система использует этот идентификатор для отправки сообщений уведомлений в окно, указанное в hWnd. Эти сообщения уведомления отправляются при наведении указателя мыши на ограничивающий прямоугольник значка, при выборе или активации значка с помощью клавиатуры или при возникновении этих действий в уведомлении о воздушных шарах.

Если элемент uVersion равен 0 или NOTIFYICON_VERSION, параметр wParam сообщения содержит идентификатор значка панели задач, в которой произошло событие. Этот идентификатор может иметь длину 32 бита. Параметр lParam содержит сообщение мыши или клавиатуры, связанное с событием. Например, при перемещении указателя на значок панели задач lParam установлено значение WM_MOUSEMOVE.

Когда NOTIFYICON_VERSION_4 элемент uVersion, приложения продолжают получать события уведомлений в виде сообщений, определенных приложением, через элемент uCallbackMessage, но интерпретация lParam и wParam параметров этого сообщения изменяется следующим образом:

  • LOWORD(lParam) содержит события уведомлений, такие как NIN_BALLOONSHOW, NIN_POPUPOPEN или WM_CONTEXTMENU.
  • HIWORD(lParam) содержит идентификатор значка. Идентификаторы значков ограничены длиной 16 бит.
  • GET_X_LPARAM (wParam) возвращает координату привязки X для событий уведомлений NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT и всех сообщений мыши между WM_MOUSEFIRST и WM_MOUSELAST. Если любой из этих сообщений создается клавиатурой, wParam устанавливается в левый верхний угол значка целевого объекта. Для всех других сообщений wParam не определен.
  • GET_Y_LPARAM(wParam) возвращает координату привязки Y для событий уведомлений и сообщений, определенных для привязки X.

hIcon

Тип: HICON

Дескриптор значка, который нужно добавить, изменить или удалить. Windows XP и более поздних версий поддерживают значки до 32 BPP.

Если указан только значок пикселя 16x16, он масштабируется до большего размера в системном наборе с высоким значением dpi. Это может привести к невлекательным результатам. Рекомендуется указать значок 16x16 пикселей и значок 32x32 в файле ресурса. Используйте LoadIconMetric, чтобы убедиться, что правильный значок загружается и масштабируется соответствующим образом. См. примечания для примера кода.

szTip[64]

Тип: TCHAR[64]

Строка, завершающая значение NULL, указывающая текст стандартной подсказки. Он может содержать не более 64 символов, включая завершающий символ NULL.

Для Windows 2000 и более поздних версий szTip могут содержать не более 128 символов, включая завершающийся символ NULL.

szTip[128]

Тип: TCHAR[64]

Строка, завершающая значение NULL, указывающая текст стандартной подсказки. Он может содержать не более 64 символов, включая завершающий символ NULL.

Для Windows 2000 и более поздних версий szTip могут содержать не более 128 символов, включая завершающийся символ NULL.

dwState

Тип: DWORD

Windows 2000 и более поздних версий. Состояние значка. Одно или оба из следующих значений:

NIS_HIDDEN (0x00000001)

0x00000001. Значок скрыт.

NIS_SHAREDICON (0x00000002)

0x00000002. Ресурс значка предоставляется совместно с несколькими значками.

dwStateMask

Тип: DWORD

Windows 2000 и более поздних версий. Значение, указывающее, какие биты элемента dwState извлекаются или изменяются. Возможные значения совпадают с значениями для dwState. Например, установка этого элемента на NIS_HIDDEN приводит к изменению только скрытого состояния элемента, в то время как бит общего доступа к значку игнорируется независимо от его значения.

szInfo[256]

Тип: TCHAR[256]

Windows 2000 и более поздних версий. Строка, завершающая значение NULL, указывающая текст, отображаемый в уведомлении о воздушных шарах. Он может содержать не более 256 символов, включая завершающий пустой символ, но должен быть ограничен 200 символами на английском языке для локализации. Чтобы удалить уведомление о воздушных шарах из пользовательского интерфейса, удалите значок (с NIM_DELETE) или установите флаг NIF_INFO в uFlags и задайте szInfo пустой строкой.

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

Тип: UINT

Windows 2000 и более поздних версий.

Примечание Этот член не рекомендуется использовать в Windows Vista. Время отображения уведомлений теперь основано на параметрах специальных возможностей системы.
 
Объединение с uVersion. Значение времени ожидания (в миллисекундах) для уведомления. Система применяет минимальные и максимальные значения времени ожидания. Значения, указанные в uTimeout, которые слишком большие, имеют максимальное значение. Значения, слишком малые по умолчанию, равные минимальному значению. Системные минимальные и максимальные значения времени ожидания в настоящее время задаются в 10 секунд и 30 секунд соответственно. Дополнительные сведения о uTimeoutсм. в примечаниях.

DUMMYUNIONNAME.uVersion

Тип: UINT

Windows 2000 и более поздних версий. Объединение с uTimeout (не рекомендуется использовать в Windows Vista). Указывает, какая версия интерфейса значка уведомления оболочки должна использоваться. Дополнительные сведения о различиях в этих версиях см. в Shell_NotifyIcon. Этот элемент используется только при использовании Shell_NotifyIcon для отправки сообщения NIM_SETVERSION.

szInfoTitle[64]

Тип: TCHAR[64]

Windows 2000 и более поздних версий. Строка, завершающаяся значением NULL, указывающая заголовок для уведомления о воздушных шарах. Этот заголовок отображается в более крупном шрифте сразу над текстом. Он может содержать не более 64 символов, включая завершающий пустой символ, но должен быть ограничен 48 символами на английском языке для локализации.

dwInfoFlags

Тип: DWORD

Windows 2000 и более поздних версий. Флаги, которые можно задать для изменения поведения и внешнего вида уведомления о воздушных шарах. Значок помещается слева от заголовка. Если элемент szInfoTitle равен нулевой длине, значок не отображается.

NIIF_NONE (0x00000000)

0x00000000. Значок нет.

NIIF_INFO (0x00000001)

0x00000001. Значок сведений.

NIIF_WARNING (0x00000002)

0x00000002. Значок предупреждения.

NIIF_ERROR (0x00000003)

0x00000003. Значок ошибки.

NIIF_USER (0x00000004)

0x00000004. Windows XP с пакетом обновления 2 (SP2) и более поздних версий.

  • Windows XP: используйте значок, указанный в hIcon в качестве значка заголовка шара уведомлений.
  • Windows Vista и более поздних версий: используйте значок, указанный в hBalloonIcon в качестве значка заголовка шара уведомлений.

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP и более поздних версий. Не воспроизводите связанный звук. Применяется только к уведомлениям.

NIIF_LARGE_ICON (0x00000020)

0x00000020. Windows Vista и более поздних версий. Большая версия значка должна использоваться в качестве значка уведомления. Это соответствует значку с измерениями SM_CXICON x SM_CYICON. Если этот флаг не задан, используется значок с измерениями SM_CXSMICON x SM_CYSMICON.

  • Этот флаг можно использовать со всеми значками акций.
  • Приложения, использующие старые настраиваемые значки (NIIF_USER с hIcon) должны предоставить новую версию SM_CXICON x SM_CYICON в значке области (hIcon). Эти значки масштабируются, когда они отображаются в области управления системой или системной области управления (SCA).
  • Новые настраиваемые значки (NIIF_USER с hBalloonIcon) должны предоставлять версию SM_CXICON x SM_CYICON в предоставленном значке (hBalloonIcon).

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080. Windows 7 и более поздних версий. Не отображайте уведомление о воздушных шарах, если текущий пользователь находится в "тихое время", что является первым часом после того, как новый пользователь впервые входит в свою учетную запись. В течение этого времени большинство уведомлений не должны отправляться или отображаться. Это позволяет пользователю привыкнуть к новой компьютерной системе без этих отвлекающих факторов. Тихое время также происходит для каждого пользователя после обновления операционной системы или очистки установки. Уведомление, отправленное с этим флагом во время тишины, не помещается в очередь; это просто отклонить. Приложение может повторно отправить уведомление позже, если оно по-прежнему допустимо в то время.

Так как приложение не может прогнозировать, когда оно может столкнуться с спокойным временем, мы рекомендуем, чтобы этот флаг всегда был установлен для всех соответствующих уведомлений любым приложением, что означает для учета спокойного времени.

В спокойное время некоторые уведомления по-прежнему должны отправляться, так как они ожидаются пользователем в качестве обратной связи в ответ на действие пользователя, например, когда он или она подключается к USB-устройству или печатает документ.

Если текущий пользователь не находится в спокойном времени, этот флаг не влияет.

NIIF_ICON_MASK (0x0000000F)

0x0000000F. Windows XP и более поздних версий. Скрытный.

guidItem

Тип: GUID

Windows XP и более поздних версий.

  • Windows 7 и более поздних версий: зарегистрированный GUID, определяющий значок. Это значение переопределяет uID и является рекомендуемой методикой идентификации значка. Флаг NIF_GUID должен быть задан в элементе uFlags.
  • Windows XP и Windows Vista: зарезервировано; должно быть установлено значение 0.
Если приложение предназначено для запуска в Windows Vista и Windows 7, необходимо проверить версию Windows и указать только ненулевое guidItem, если в Windows 7 или более поздней версии.

Если вы идентифицируете значок уведомления с GUID в одном вызове Shell_NotifyIcon, необходимо использовать тот же GUID для идентификации значка в любых последующих вызовах Shell_NotifyIcon, которые имеют тот же значок.

Чтобы создать GUID для использования в этом элементе, используйте средство создания GUID, например Guidgen.exe.

hBalloonIcon

Тип: HICON

Windows Vista и более поздних версий. Дескриптор настраиваемого значка уведомления, предоставленного приложением, которое должно использоваться независимо от значка области уведомлений. Если этот элемент не имеет значения NULL, а флаг NIIF_USER задан в элементе dwInfoFlags, этот значок используется в качестве значка уведомления. Если этот элемент null, выполняется устаревшее поведение.

Замечания

Дополнительные сведения о пользовательском интерфейсе и рекомендациях по контенту см. в разделе "Уведомления" в руководстве по взаимодействию с пользователем Windows.

Если задать флаг NIF_INFO в элементе uFlags, используется уведомление в стиле воздушных шаров. Дополнительные сведения об этих уведомлениях см. в всплывающих подсказках.

На панели задач может отображаться не более одного уведомления о воздушных шарах. Если приложение пытается отобразить уведомление, когда оно уже отображается, новое уведомление помещается в очередь и отображается при удалении старого уведомления. В версиях Windows до Windows Vista новое уведомление не будет отображаться до тех пор, пока существующее уведомление не отображается по крайней мере для минимальной продолжительности времени ожидания системы, независимо от значения исходного уведомления uTimeout. Если пользователь, как представляется, не использует компьютер, система не учитывает это время до истечения времени ожидания.

Для Windows 2000 и более поздних версий поддерживается несколько членов этой структуры. Чтобы включить эти элементы, добавьте одну из следующих строк в заголовок:

// 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

Обратите внимание, что необходимо инициализировать структуру с его размером. Если вы используете размер определенной в настоящее время структуры, приложение может не запускаться с более ранними версиями Shell32.dll, что ожидает меньшей структуры. Вы можете запустить приложение в более ранних версиях Shell32.dll, определив соответствующий номер версии (см. версии оболочки и распространенных элементов управления). Однако это может привести к проблемам, если приложение также должно работать в более поздних системах.

Вы можете поддерживать совместимость приложений со всеми версиями Shell32.dll при использовании текущих файлов заголовков, задав размер структуры NOTIFYICONDATA. Прежде чем инициализировать структуру, используйте DllGetVersion , чтобы определить, какая версия Shell32.dll установлена в системе и инициализирует cbSize с одним из следующих значений:

версия Shell32.dll cbSize
6.0.6 или более поздней версии (Windows Vista и более поздней версии) sizeof(NOTIFYICONDATA)
6.0 (Windows XP) NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000) NOTIFYICONDATA_V2_SIZE
Версии ниже 5.0 NOTIFYICONDATA_V1_SIZE
 

Это значение для cbSize позволяет приложению использовать NOTIFYICONDATA в методе, совместимом с более ранними версиями Shell32.dll.

В следующем примере кода показана проверка версий, которая может включить приложение, использующее guidItem для запуска в Windows Vista и Windows 7. Она предоставляет логическую функцию, которая возвращает TRUE, если операционная система — Windows 7. Если этот элемент не возвращает TRUE, элемент guidItem должен иметь значение 0.

примечание Этот код относится к номеру версии Windows 7. Ожидается, что будущие версии Windows и Windows Server будут поддерживать элемент guidItem, и в то время этот код необходимо обновить, чтобы определить более поздние номера версий так же, как допустимые.
 
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);
}

В следующем примере кода показано использование LoadIconMetric для загрузки значка для использования с высоким уровнем DPI.

// 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;

устранение неполадок

Если вы используете элемент guidItem для идентификации значка, и этот значок не отображается или некоторые вызовы Shell_NotifyIcon сбой, один из следующих случаев является вероятным причиной:
  1. Флаг NIF_GUID не был задан в каждом вызове Shell_NotifyIcon. После идентификации значка уведомления с GUID в одном вызове Shell_NotifyIconнеобходимо использовать тот же GUID для идентификации значка в любых последующих вызовах Shell_NotifyIcon, которые имеют дело с этим значком.
  2. Двоичный файл, содержащий значок, был перемещен. Путь к двоичному файлу включается в регистрацию GUID значка и не может быть изменен. Параметры, связанные с значком, сохраняются при обновлении только в том случае, если путь к файлу и GUID не изменяются. Если путь необходимо изменить, приложение должно удалить все сведения GUID, добавленные при регистрации существующего значка. После удаления этой информации можно переместить двоичный файл в новое расположение и повторно зарегистрировать его с помощью нового GUID. Все параметры, связанные с исходной регистрацией GUID, будут потеряны.

    Это также происходит в случае параллельной установки. При работе с параллельной установкой новые версии приложения должны обновить GUID двоичного файла.

    Примечание Единственное исключение для перемещаемого файла возникает, когда исходные и перемещаемые двоичные файлы Authenticodeподписаны одной и той же компанией. В этом случае параметры сохраняются через перемещение.
     

Заметка

Заголовок shellapi.h определяет NOTIFYICONDATA как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [только классические приложения]
минимальный поддерживаемый сервер Windows 2000 Server [только классические приложения]
заголовка shellapi.h

См. также

уведомления и область уведомлений