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

Статья
03/15/2023

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

Синтаксис

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.
Если пользователь выбирает значок уведомления с помощью клавиатуры и активирует его с помощью клавиши SPACEBAR или ВВОД, оболочка 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 или предварительной версии 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	shellapi.h
библиотеки	Shell32.lib
DLL	Shell32.dll (версия 4.0 или более поздняя версия)
набор API	ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240)

См. также

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

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