Método ITaskbarList3::SetOverlayIcon (shobjidl_core.h)

Aplica una superposición a un botón de barra de tareas para indicar el estado de la aplicación o una notificación al usuario.

Sintaxis

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

Parámetros

[in] hwnd

Tipo: HWND

Identificador de la ventana cuyo botón de barra de tareas asociado recibe la superposición. Este identificador debe pertenecer a un proceso de llamada asociado a la aplicación del botón y debe ser un HWND válido o se omite la llamada.

[in] hIcon

Tipo: HICON

Manipulador de un icono que se usará como superposición. Debe ser un icono pequeño, midiendo 16 x 16 píxeles a 96 ppp. Si ya se ha aplicado un icono de superposición al botón de la barra de tareas, se reemplazará la superposición actual.

Este valor puede ser NULL. El modo en que se controla un valor NULL depende de si el botón de la barra de tareas representa una sola ventana o un grupo de ventanas.

• Si el botón de la barra de tareas representa una sola ventana, el icono de superposición se quita de la pantalla.
• Si el botón de la barra de tareas representa un grupo de ventanas y una superposición anterior todavía está disponible (recibido antes de la superposición actual, pero aún no liberado por un valor NULL ), esa superposición anterior se muestra en lugar de la superposición actual.

Es responsabilidad de la aplicación que realiza la llamada liberar hIcon cuando ya no es necesario. Por lo general, esto se puede hacer después de llamar a SetOverlayIcon porque la barra de tareas realiza y usa su propia copia del icono.

[in] pszDescription

Tipo: LPCWSTR

Puntero a una cadena que proporciona una versión de texto alternativo de la información transmitida por la superposición con fines de accesibilidad.

Valor devuelto

Tipo: HRESULT

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

En versiones de Windows anteriores a Windows 7, las aplicaciones suelen usar iconos en el área de notificación de la barra de tareas para mostrar el estado y las notificaciones de la aplicación al usuario. La barra de tareas de Windows 7 permite a una aplicación proporcionar ese mismo tipo de comentarios de usuario a través de su botón de barra de tareas, centralizando más información de la aplicación en un solo lugar. Estas superposiciones son similares a las superposiciones existentes que se usan para los iconos de acceso directo o las notificaciones de seguridad, que se muestran en la esquina inferior derecha del botón.

En la ilustración siguiente se muestra una superposición (el cuadrado verde pequeño que indica el estado del usuario como "Disponible") aplicado al botón de la barra de tareas de extremo derecho.

Las superposiciones de icono sirven como una notificación contextual del estado y están pensadas para negar la necesidad de un icono de estado de área de notificación independiente para comunicar esa información al usuario. El diseñador de aplicaciones debe decidir durante el ciclo de desarrollo qué método(icono de superposición de icono o icono de estado del área de notificación) sirve mejor a esa aplicación. Los iconos de superposición están diseñados para proporcionar notificaciones o estados importantes, de larga duración, como el estado de red, el estado del mensajero o el nuevo correo. No deben cambiarse con frecuencia, ni deben animarse.

Para mostrar un icono de superposición, la barra de tareas debe estar en el modo de icono grande predeterminado. Si la barra de tareas se configura a través de las propiedades de la barra de tareas y del menú Inicio para mostrar iconos pequeños, no se pueden aplicar superposiciones y se omiten las llamadas a este método.

Dado que se aplica una sola superposición al botón de la barra de tareas en lugar de a las miniaturas de ventana individuales, se trata de una característica por grupo en lugar de por ventana. Las solicitudes de iconos de superposición se pueden recibir de ventanas individuales en un grupo de barras de tareas, pero no se ponen en cola. La última superposición recibida es la superposición mostrada. Si se quita la última superposición recibida, la superposición que ha reemplazado se restaura siempre y cuando todavía esté activa. Por ejemplo, las ventanas 1, 2 y 3 establecen, en orden, superponen A, B y C. Dado que la superposición C se recibió por última vez, se muestra en el botón de la barra de tareas. La ventana 2 llama a SetOverlayIcon con un valor NULL para quitar la superposición B. La ventana 3 hace lo mismo para quitar la superposición C. Dado que la superposición de la ventana 1 A sigue activa, esa superposición se muestra en el botón de la barra de tareas.

Si el Explorador de Windows se cierra inesperadamente, las superposiciones no se restauran cuando se restaura el Explorador de Windows. La aplicación debe esperar para recibir el mensaje TaskbarButtonCreated que indica que el Explorador de Windows se ha reiniciado y se ha vuelto a crear el botón de la barra de tareas y, a continuación, llamar a SetOverlayIcon de nuevo para volver a aplicar la superposición.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shobjidl_core.h (incluya Shobjidl.h)
Library	Explorerframe.lib
Archivo DLL	Explorerframe.dll

Consulte también

ITaskbarList

ITaskbarList2

ITaskbarList3

Extensiones de la barra de tareas