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

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 NOTIFYICONDATA a la que apunta lpdata, ya sea a través de su miembro uID o 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. La estructura 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. La estructura 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. 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. Indica al área de notificación que se comporte según el número de versión especificado en el miembro 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 detalles al respecto, consulte la sección Comentarios.

[in] lpData

Tipo: PNOTIFYICONDATA

Puntero a una estructura 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

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.

Comentarios

A partir de Windows 2000 (Shell32.dll versión 5.0), si estableces el miembro uVersion de la estructura NOTIFYICONDATA a la que apunta lpdata en NOTIFYICON_VERSION_4 o superior, Shell_NotifyIcon eventos de mouse y teclado se controlan de forma diferente a 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, el 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 de 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 desaparece el globo. 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 una notificación con la marca de NIIF_RESPECT_QUIET_TIME establece intentos de mostrar durante el tiempo de silencio (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 de texto 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 de la estructura NOTIFYICONDATA a la que apunta lpdata para indicar si desea que 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 valor lParam del mensaje definido por la aplicación que se especifica en el miembro uCallbackMessage de la estructura 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shellapi.h
Library Shell32.lib
Archivo DLL Shell32.dll (versión 4.0 o posterior)
Conjunto de API ext-ms-win-shell-shell32-l1-2-1 (introducido en Windows 10, versión 10.0.10240)

Consulte también

Notificaciones y el área de notificación