функция Shell_NotifyIconA (shellapi.h)

  • Статья

Отправляет сообщение в область состояния панели задач.

Синтаксис

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

Параметры

[in] dwMessage

Тип: DWORD

Значение типа , указывающее действие, выполняемое данной функцией. Может иметь одно из следующих значений:

NIM_ADD (0x00000000)

0x00000000. Добавляет значок в область состояния. Значок получает идентификатор в структуре NOTIFYICONDATA , на которую указывает lpdata— через его uID или элемент guidItem . Этот идентификатор используется в последующих вызовах Shell_NotifyIcon для выполнения последующих действий со значком.

NIM_MODIFY (0x00000001)

0x00000001. Изменяет значок в области состояния. Структура NOTIFYICONDATA, на которую указывает lpdata, использует идентификатор, изначально назначенный значку при добавлении в область уведомлений (NIM_ADD), для идентификации значка, который требуется изменить.

NIM_DELETE (0x00000002)

0x00000002. Удаляет значок из области состояния. Структура NOTIFYICONDATA, на которую указывает lpdata, использует идентификатор, изначально назначенный значку при добавлении в область уведомлений (NIM_ADD), для идентификации удаляемого значка.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll только версии 5.0 и более поздних версий. Возвращает фокус в область уведомлений панели задач. Значки области уведомлений должны использовать это сообщение после завершения операции пользовательского интерфейса. Например, если на значке отображается контекстное меню, но пользователь нажимает клавишу ESC, чтобы отменить его, используйте NIM_SETFOCUS , чтобы вернуть фокус в область уведомлений.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll только версии 5.0 и более поздних версий. Указывает, что область уведомлений будет работать в соответствии с номером версии, указанным в элементе uVersion структуры, на которую указывает lpdata. Номер версии указывает, какие элементы распознаются.

NIM_SETVERSION необходимо вызывать при каждом добавлении значка области уведомлений (NIM_ADD). Его не нужно вызывать с помощью NIM_MODIFY. Параметр версии не сохраняется после выхода пользователя из системы.

Подробные сведения см. в разделе "Заметки".

[in] lpData

Тип: PNOTIFYICONDATA

Указатель на структуру NOTIFYICONDATA . Содержимое структуры зависит от значения dwMessage. Он может определить значок для добавления в область уведомлений, вызвать отображение этого значка уведомления или определить значок для изменения или удаления.

Возвращаемое значение

Тип: BOOL

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Если параметру dwMessage присвоено значение NIM_SETVERSION, функция возвращает значение TRUE , если версия была успешно изменена, или FALSE , если запрошенная версия не поддерживается.

Комментарии

Начиная с Windows 2000 (Shell32.dll версии 5.0), если для элемента uVersion структуры NOTIFYICONDATA , на которую указывает lpdata , задано значение NOTIFYICON_VERSION_4 или более поздней версии, события мыши и клавиатуры Shell_NotifyIcon обрабатываются иначе, чем в более ранних версиях Windows. Ниже перечислены различия.

  • Если пользователь выбирает контекстное меню значка уведомления с помощью клавиатуры, оболочка отправляет связанному приложению WM_CONTEXTMENU сообщение. Более ранние версии отправляют сообщения WM_RBUTTONDOWN и WM_RBUTTONUP .
  • Если пользователь выбирает значок уведомления с клавиатуры и активирует его с помощью клавиши ПРОБЕЛ или ВВОД, оболочка версии 5.0 отправляет связанному приложению уведомление NIN_KEYSELECT. Более ранние версии отправляют сообщения WM_RBUTTONDOWN и WM_RBUTTONUP .
  • Если пользователь выбирает значок уведомления с помощью мыши и активирует его с помощью клавиши ВВОД, оболочка отправляет связанному приложению уведомление NIN_SELECT. Более ранние версии отправляют сообщения WM_RBUTTONDOWN и WM_RBUTTONUP .
Начиная с Windows XP (Shell32.dll версии 6.0), если пользователь передает указатель мыши на значок, с которым связано всплывающее уведомление, оболочка отправляет следующие сообщения:
  • NIN_BALLOONSHOW. Отправляется при отображении выноски (выноски помещаются в очередь).
  • NIN_BALLOONHIDE. Отправляется, когда воздушный шар исчезает. Например, при удалении значка. Это сообщение не отправляется, если выноска закрывается из-за истечения времени ожидания или если пользователь щелкает мышью.

    В Windows 7 NIN_BALLOONHIDE также отправляется, когда уведомление с флагом NIIF_RESPECT_QUIET_TIME пытается отобразиться в неспокойное время (первый час пользователя на новом компьютере). В этом случае воздушный шар вообще не отображается.

  • NIN_BALLOONTIMEOUT. Отправляется при закрытии выноски из-за истечения времени ожидания.
  • NIN_BALLOONUSERCLICK. Отправляется при закрытии выноски из-за того, что пользователь нажал мышь.
В дополнение к этим сообщениям, начиная с Windows Vista (Shell32.dll версии 6.0.6), если пользователь передает указатель мыши на значок, с которым связано всплывающее уведомление, оболочка Windows Vista также добавляет следующие сообщения:
  • NIN_POPUPOPEN. Отправляется, когда пользователь наведен курсор на значок, чтобы указать, что вместо стандартной текстовой подсказки следует использовать более широкий пользовательский интерфейс.
  • NIN_POPUPCLOSE. Отправляется, когда курсор больше не наведен на значок, чтобы указать, что расширенный пользовательский интерфейс должен быть закрыт.
Независимо от версии операционной системы, можно выбрать способ работы оболочки, вызвав Shell_NotifyIcon с параметром dwMessage , равным NIM_SETVERSION. Задайте элемент uVersion структуры NOTIFYICONDATA , на который указывает lpdata , чтобы указать, требуется ли поведение Windows 2000, Windows Vista или windows 5.0 (Windows 95).
Примечание Описанные выше сообщения не являются обычными сообщениями Windows. Они отправляются в виде значения lParam определяемого приложением сообщения, указанного в элементе uCallbackMessage структуры NOTIFYICONDATA , на которую указывает lpdata, при вызове Shell_NotifyIcon с флагом NIM_ADD , установленным в dwMessage.
 
В Windows XP с пакетом обновления 2 (SP2) на всплывающем окне уведомления может отображаться пользовательский значок. Это позволяет вызывающему процессу настраивать уведомление за пределами ранее доступных параметров сведений, предупреждений и ошибок, а также отличать его от других типов уведомлений для пользователя.

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header shellapi.h
Библиотека Shell32.lib
DLL Shell32.dll (версия 4.0 или более поздняя)
Набор API ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240)

См. также раздел

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