Introduction

The system tray icon notification area -- or "systray" or "taskbar notification system area" -- is a section of the taskbars in the Microsoft Windows desktop user interface. This section displays the clock and the icons of certain programs so that a user is continually reminded that they are there and can easily click one of them. Unfortunately, MFC does not contain a class to wrap system tray functionality. So, I decided to write one and put it up for public use.

Background

The system tray is a section located at the one end of the taskbar in Windows 9x, and NT (Family). Icons that are often installed in the system tray include the volume control for sound, anti-virus software, and a system resources indicator. When more icons are installed in the system tray than can fit in the space allotted, the system tray becomes horizontally scrollable or expandable. To interact with a program in the system tray, you select an icon with your mouse and double-click or right-click the icon. When you minimize the program after using it, it shrinks back into the system tray instead of into the main part of the taskbar.

What makes a system tray icon special is that, when installed, it can have a customized message appear when the mouse is hovering over it. The menu that appears when you right-click it can be customized and the action that occurs when you double-click it can also be customized. For example, the double-click action for Internet Explorer could be to launch (start, or open a window for) the program, but the double-click action for a desktop icon could be to "View desktop," i.e. remove the active windows and show the underlying desktop.

An icon can be placed in the system tray when a program is installed by making an entry in the system registry. It can also be placed later by creating a shortcut to a program and dragging the shortcut icon to the system tray. An icon can be removed by deleting the registry entry or by right-clicking it and selecting Delete on the pop-up menu. The clock is removed by deselecting the show clock option in the taskbar Properties.

About CTrayIcon

CTrayIcon lets VC++ developers add icons to the Windows system tray. This quickly makes any VC++ application more attractive and intuitive to Windows users.

CTrayIcon can display pop-ups. This allows developers to modify the look and feel and add powerful menu items.

With CTrayIcon, tray icons can have Tool Tip Text that appears during a mouse-over. In addition, a cool mouse-hover effect is provided.

CTrayIcon class summary

This class is a wrap around the system tray icon notification. It adds a specified set of icon-pairs -- i.e. icons & hover-icons -- and tooltips to the system tray notification area, as well as a callback notification handler for mouse message handling.

Parameters

pWnd: Pointer to the window that receives notification messages associated with an icon in the taskbar status area. If the pWnd parameter is not provided, then the function CTrayIcon::OnNotifyIcon will be called whenever the icon sends a notification message.

uNotificationMessage: Message identifier for handling proper mouse notification messages associated with an icon in the taskbar status area. If a uNotificationMessage parameter is not provided, then a new window message is registered -- i.e. ::RegisterWindowMessage(_T("NotifyIcon") -- and is used as a default notification message identifier.

pMouseMsgHandlerPtr: An array of pointers to objects of classes derived from CTrayIconMouseMsgHandler to handle mouse messages.

uHandlersCount: Indicates the number of handlers in the array pointed to by pMouseMsgHandlerPtr.

pIconDataPtr: An array of pointers to objects of CIconData -- i.e. units of icons, hover icons, and tool tips -- to be added to the taskbar status area.

uIconsCount: Indicates the number of icons in the array pointed to by p IconDataPtr.

nSelectedIconIndex: Index of the selected icon in the array pointed to by p IconDataPtr.

uElapsed: Indicates the elapsed time for the taskbar status area icon animation timer.

OnTimer

Syntax

CTrayIconMouseMsgHandler class summary

This class stands as an abstract base-class for handling mouse notification messages. Classes derived from CTrayIconMouseMsgHandler should handle mouse notification messages and must implement the pure-virtual MouseMessageHandler() method.

CTrayIconMouseMsgHandler construction

Only a single parameter constructor is available that takes a Window message to be associated with it for receiving other system tray icon notification messages.

CTrayIconMouseMsgHandler getters and setters

CTrayIconMouseMsgHandler events & callbacks

MouseMsgHandler

This method is a pure-virtual method and must be defined in the derived classes for handling system tray icon mouse notification messages. This event is generated by the CTrayIcon::OnNotifyIcon() method.

CTrayIconMouseMsgHandler synonyms

MouseMsgHandlerPtr

CIconData class summary

This class encapsulates a set of icon-pairs -- i.e. icons & hover-icons -- and tooltips for the system tray notification area. It wraps the basic functionality to switch between icon & hover-icon, as well as between two different CIconData objects along with their respective tooltips.

CIconData construction

For object creation, a quad parameter constructor is available that takes icon-pair (icon & hover-icon) identifiers -- where hover-icon is optional -- a tooptip and an optional handler to an icon.

Parameters

uDefaultIconID: Application-defined identifier of an icon, to be showed in the system tray icon notification area.

lpToolTip: Pointer to a null-terminated string with the text for a standard ToolTip. It can have a maximum of 64 characters, including the terminating NULL.

uHoverIconID: Application-defined identifier of an icon, to be showed in the system tray icon notification area during mouse-hover.

hIcon: Handle to the icon to be added, modified or deleted. To avoid icon distortion, be aware that notification area icons have different levels of support under different versions of Microsoft® Windows®. Windows 95, Windows 98, and Microsoft Windows NT® 4.0 support icons of up to 4 bits per pixel (BPP). Windows Millennium Edition (Windows Me) and Windows 2000 support icons of a color depth up to the current display mode. Windows XP supports icons of up to 32 BPP.

Step 7 - the finishing touch

Alternate step - the other way around

In the above steps, we saw how efficiently we can handle the system tray notification icon messages by using the CTrayIcon class. What if you want to handle those messages in you own CWnd class? Implement this phase if you'd like to handle the system tray notification icon messages in you CWnd or CDialog class. In this example, that class would be the CCTrayIconDemoDlg class. Go to the header file and register a Window message to be handled once the system tray notification icon is created.

History

23 August, 2004 -- Original version posted

6 June, 2007 -- Article and downloads updated

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Hi,
Thanks for your class. It saves me a lot of time.
However, I don't know how to display the menu on the current mouse position when users right click the tray icon.
Can you tell me which function to use to retrieve current mouse position?