Compartir a través de

función Shell_NotifyIconA (shellapi.h)

  • Artículo

Envía un mensaje al área de estado de la barra de tareas.

Sintaxis

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

Parámetros

[in] dwMessage

Tipo: DWORD de

Valor que especifica la acción que debe realizar esta función. Puede tener uno de los siguientes valores:

NIM_ADD (0x00000000)

0x00000000. Agrega un icono al área de estado. El icono recibe un identificador en la estructura de de NOTIFYICONDATA a la que apunta lpdata, ya sea a través de su uID de o miembro guidItem. Este identificador se usa en llamadas posteriores a Shell_NotifyIcon para realizar acciones posteriores en el icono.

NIM_MODIFY (0x00000001)

0x00000001. Modifica un icono en el área de estado. estructura de NOTIFYICONDATA a la que apunta lpdata usa el identificador asignado originalmente al icono cuando se agregó al área de notificación (NIM_ADD) para identificar el icono que se va a modificar.

NIM_DELETE (0x00000002)

0x00000002. Elimina un icono del área de estado. estructura de NOTIFYICONDATA a la que apunta lpdata usa el identificador asignado originalmente al icono cuando se agregó al área de notificación (NIM_ADD) para identificar el icono que se va a eliminar.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll versión 5.0 y versiones posteriores solo. Devuelve el foco al área de notificación de la barra de tareas. Los iconos del área de notificación deben usar este mensaje cuando hayan completado su operación de interfaz de usuario. Por ejemplo, si el icono muestra un menú contextual, pero el usuario presiona ESC para cancelarlo, use NIM_SETFOCUS para devolver el foco al área de notificación.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll versión 5.0 y versiones posteriores solo. Indica al área de notificación que se comporte según el número de versión especificado en el miembro de uVersion de la estructura a la que apunta lpdata. El número de versión especifica qué miembros se reconocen.

NIM_SETVERSION se debe llamar cada vez que se agrega un icono de área de notificación (NIM_ADD). No es necesario llamar a con NIM_MODIFY. La configuración de versión no se conserva una vez que un usuario cierra sesión.

Para obtener más información, consulte la sección Comentarios.

[in] lpData

Tipo: PNOTIFYICONDATA

Puntero a una estructura de NOTIFYICONDATA. El contenido de la estructura depende del valor de dwMessage. Puede definir un icono para agregar al área de notificación, hacer que ese icono muestre una notificación o identifique un icono para modificar o eliminar.

Valor devuelto

Tipo: BOOL de

Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Si dwMessage se establece en NIM_SETVERSION, la función devuelve TRUE si la versión se cambió correctamente o FALSE si no se admite la versión solicitada.

Observaciones

A partir de Windows 2000 (Shell32.dll versión 5.0), si estableces el miembro uVersion del NOTIFYICONDATA estructura apuntada por lpdata en NOTIFYICON_VERSION_4 o superior, los eventos de mouse y teclado Shell_NotifyIcon se controlan de forma diferente que en versiones anteriores de Windows. Entre las diferencias se incluyen las siguientes:

  • Si un usuario selecciona el menú contextual de un icono de notificación con el teclado, shell ahora envía a la aplicación asociada un mensaje de WM_CONTEXTMENU. Las versiones anteriores envían mensajes WM_RBUTTONDOWN y WM_RBUTTONUP.
  • Si un usuario selecciona un icono de notificación con el teclado y lo activa con la tecla SPACEBAR o ENTER, shell de la versión 5.0 envía a la aplicación asociada una notificación de NIN_KEYSELECT. Las versiones anteriores envían mensajes WM_RBUTTONDOWN y WM_RBUTTONUP.
  • Si un usuario selecciona un icono de notificación con el mouse y lo activa con la tecla ENTRAR, shell ahora envía a la aplicación asociada una notificación NIN_SELECT. Las versiones anteriores envían mensajes WM_RBUTTONDOWN y WM_RBUTTONUP.
A partir de Windows XP (Shell32.dll versión 6.0), si un usuario pasa el puntero del mouse sobre un icono con el que está asociada una notificación de globo, shell envía los siguientes mensajes:
  • NIN_BALLOONSHOW. Se envía cuando se muestra el globo (los globos se ponen en cola).
  • NIN_BALLOONHIDE. Enviado cuando el globo desaparece. Por ejemplo, cuando se elimina el icono. Este mensaje no se envía si el globo se descarta debido a un tiempo de espera o si el usuario hace clic en el mouse.

    A partir de Windows 7, también se envía NIN_BALLOONHIDE cuando se envía una notificación con el conjunto de marcas NIIF_RESPECT_QUIET_TIME intenta mostrarse durante el tiempo silencioso (la primera hora de un usuario en un equipo nuevo). En ese caso, el globo nunca se muestra en absoluto.

  • NIN_BALLOONTIMEOUT. Se envía cuando se descarta el globo debido a un tiempo de espera.
  • NIN_BALLOONUSERCLICK. Se envía cuando se descarta el globo porque el usuario hizo clic en el mouse.
Además de esos mensajes, a partir de Windows Vista (Shell32.dll versión 6.0.6), si un usuario pasa el puntero del mouse sobre un icono con el que está asociada una notificación de globo, el Shell de Windows Vista también agrega los siguientes mensajes:
  • NIN_POPUPOPEN. Se envía cuando el usuario mantiene el cursor sobre un icono para indicar que se debe usar la interfaz de usuario emergente más completa en lugar de una información sobre herramientas textuales estándar.
  • NIN_POPUPCLOSE. Se envía cuando un cursor ya no mantiene el puntero sobre un icono para indicar que se debe cerrar la interfaz de usuario emergente enriquecida.
Independientemente de la versión del sistema operativo, puede seleccionar de qué manera debe comportarse shell llamando a Shell_NotifyIcon con dwMessage establecido en NIM_SETVERSION. Establezca el miembro uVersion del NOTIFYICONDATA estructura a la que apunta lpdata para indicar si quieres el comportamiento de Windows 2000, Windows Vista o versión preliminar 5.0 (Windows 95).
Nota Los mensajes descritos anteriormente no son mensajes convencionales de Windows. Se envían como el lParam valor del mensaje definido por la aplicación especificado en el miembro uCallbackMessage de la estructura de NOTIFYICONDATA a la que apunta lpdata, cuando se llama a Shell_NotifyIcon con la marca NIM_ADD establecida en dwMessage.
 
A partir de Windows XP Service Pack 2 (SP2), se puede mostrar un icono personalizado en el globo de notificación. Esto permite que el proceso de llamada personalice la notificación más allá de las opciones de información, advertencia y error disponibles anteriormente, y distinguirla de otros tipos de notificación para el usuario.

Nota

El encabezado shellapi.h define Shell_NotifyIcon como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de Windows
encabezado de shellapi.h
biblioteca de Shell32.lib
DLL de Shell32.dll (versión 4.0 o posterior)
conjunto de API de ext-ms-win-shell-shell32-l1-2-1 (introducido en Windows 10, versión 10.0.10240)

Consulte también

Notificaciones de y el área de notificaciones