Метод ITaskbarList3::SetOverlayIcon (shobjidl_core.h)

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

Синтаксис

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

Параметры

[in] hwnd

Тип: HWND

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

[in] hIcon

Тип: HICON

Дескриптор значка, используемого в качестве наложения. Это должен быть небольшой значок размером 16 x 16 пикселей с разрешением 96 точек на дюйм. Если к кнопке панели задач уже применен значок наложения, это существующее наложение заменяется.

Это значение может иметь значение NULL. Способ обработки значения NULL зависит от того, представляет ли кнопка панели задач одно окно или группу окон.

• Если кнопка панели задач представляет одно окно, значок наложения удаляется с экрана.
• Если кнопка панели задач представляет группу окон и предыдущее наложение по-прежнему доступно (полученное раньше текущего наложения, но еще не освобождено значением NULL ), то предыдущее наложение отображается вместо текущего наложения.

Вызывающее приложение отвечает за освобождение hIcon , когда он больше не нужен. Обычно это можно сделать после вызова SetOverlayIcon , так как панель задач создает и использует собственную копию значка.

[in] pszDescription

Тип: LPCWSTR

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

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

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Комментарии

В более ранних версиях Windows, чем Windows 7, приложения часто использовали значки в области уведомлений на панели задач для отображения состояния приложения и уведомлений для пользователя. Панель задач Windows 7 позволяет приложению предоставлять такую же обратную связь пользователей с помощью кнопки панели задач, централизации большего количества сведений о приложении в одном месте. Эти наложения похожи на существующие наложения, используемые для значков ярлыков или уведомлений безопасности, отображаемых в правом нижнем углу кнопки.

На следующем рисунке показано наложение (небольшой зеленый квадрат, указывающий состояние пользователя "Доступно"), примененное к кнопке правой панели задач.

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

Чтобы отобразить значок наложения, панель задач должна находиться в режиме больших значков по умолчанию. Если панель задач настроена в свойствах панели задач и меню "Пуск" для отображения небольших значков, наложения не могут быть применены, а вызовы этого метода игнорируются.

Так как одно наложение применяется к кнопке панели задач, а не к отдельным эскизам окна, это функция для каждой группы, а не для каждого окна. Запросы на значки наложения можно получать из отдельных окон в группе панели задач, но они не помещаются в очередь. Последнее полученное наложение — показанное наложение. Если последнее полученное наложение удаляется, замененное наложение восстанавливается до тех пор, пока оно по-прежнему активно. Например, окна 1, 2 и 3 устанавливают по порядку наложения A, B и C. Поскольку наложение C было получено последним, оно отображается на кнопке панели задач. Окно 2 вызывает Метод SetOverlayIcon со значением NULL , чтобы удалить наложение B. Затем окно 3 делает то же самое, чтобы удалить наложение C. Так как наложение A окна 1 по-прежнему активно, это наложение отображается на кнопке панели задач.

Если windows Обозреватель неожиданно завершает работу, наложения не восстанавливаются при восстановлении Windows Обозреватель. Приложение должно ожидать получения сообщения TaskbarButtonCreated о том, что Обозреватель Windows перезапущена и кнопка панели задач создана повторно, а затем снова вызовите SetOverlayIcon, чтобы повторно применить наложение.

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
Библиотека	Explorerframe.lib
DLL	Explorerframe.dll

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

ITaskbarList

ITaskbarList2

ITaskbarList3

Расширения панели задач