Windows Mobile 6.5 System Tray Icon APIs

In Windows Mobile 6.5, background utilities and minimized applications remained accessible through specific shell APIs that placed interactive status icons in the operating system's title bar and taskbar areas. By utilizing the classic Windows CE Shell_NotifyIcon function alongside the mobile-specific SHNotificationAdd suite, developers could register persistent system tray indicators, capture user tap events, and display bubble notifications to bring background processes back into focus.

The Standard Implementation: Shell_NotifyIcon

The primary API for managing system tray presence across Windows CE and Windows Mobile was Shell_NotifyIcon, declared in shellapi.h. This function allowed background processes to add, modify, or delete icons directly from the system tray area located in the navigation bar.

To use Shell_NotifyIcon, developers populated the NOTIFYICONDATA structure with the following essential parameters:

  • cbSize: The size of the NOTIFYICONDATA structure in bytes.
  • hWnd: The handle to the window that receives notification messages associated with the icon.
  • uID: An application-defined identifier for the tray icon, allowing a single process to host multiple distinct icons.
  • uFlags: Flags indicating which members of the structure contain valid data, such as NIF_ICON, NIF_MESSAGE, or NIF_TIP.
  • uCallbackMessage: A custom application-defined message identifier (typically starting at WM_APP or WM_USER) that the system sends to hWnd when the user taps or interacts with the icon.
  • hIcon: The handle to the specific 16x16 icon resource to be drawn in the tray.

The API supported three primary actions passed as message flags:

  • NIM_ADD: Places the icon into the notification area.
  • NIM_MODIFY: Updates an existing icon's image, tooltip, or callback message.
  • NIM_DELETE: Removes the icon when the background tool exits.

Advanced Mobile Notifications: SHNotificationAdd

While Shell_NotifyIcon provided baseline taskbar capability, Windows Mobile featured an enhanced API suite via aygshell.h designed specifically for touch devices: SHNotificationAdd, SHNotificationUpdate, and SHNotificationRemove.

Using the SHNOTIFICATIONDATA structure, SHNotificationAdd allowed background applications to place rich notification icons in the title bar that integrated with the Windows Mobile notification broker. Key capabilities of this API included:

  • HTML Support: Displaying rich HTML bubble dialogs when the user tapped the tray icon.
  • Persistent vs. Transient States: Setting flags like SHNF_SILENT or timeout durations, allowing a background utility to remain quietly accessible or actively alert the user.
  • Direct Command Routing: Binding the icon directly to soft keys and menu commands without requiring an immediate window restore.

Interaction and Event Handling

For background tools to remain useful, they relied on message loops bound to the tray icon callbacks. When a user tapped an icon registered via Shell_NotifyIcon, the operating system forwarded a message containing the icon's uID in the wParam parameter and the mouse/stylus event (such as WM_LBUTTONUP) in the lParam parameter. Upon receiving WM_LBUTTONUP, the background tool's hidden message window would execute the necessary action—typically displaying a pop-up context menu via TrackPopupMenu or restoring the main application window using ShowWindow(hWnd, SW_SHOWNORMAL).