Adding Application Icons to the Task Bar

Download the code for this issue

The tray notification area (TNA) of a Windows operating system is a small window located at the right or bottom edge of the taskbar when the taskbar is aligned horizontally or vertically. If the TNA acronym sounds unfamiliar, I'll tell you that the TNA is just the area of the desktop where the clock is normally displayed. Depending on the installed software and the Windows configuration, a few tray icons can be displayed close to the clock, representing apps that are currently working in the background.

Since Windows 95, Microsoft defined a set of API calls to control and configure the tray area. The Win32 SDK lets you add and delete icons, and define text and menus being displayed. These operations are all accomplished through a single API function — Shell_NotifyIcon.

The .NET Framework wraps this API into an invisible control named NotifyIcon. (An invisible control is a control that can be programmatically controlled, but results in no user interface.)

The Programming Interface of NotifyIcon

The NotifyIcon class is sealed (that is, not further inheritable) and inherits from Component not Windows.Forms.Control. This means that the NotifyIcon component is not a control in the true sense of the word. In the .NET Framework, all controls are components (i.e., implement the IComponent interface), but the reverse is not true. A Control is a component that provides UI capabilities. We'll see later in the article how this seemingly minimal difference can make some features quite hard to code.

The NotifyIcon class provides three key properties — Visible, Icon, and Text. The Visible property enables the output of the icon and the tooltip. The Icon property contains the icon to display. It can display an icon embedded in the assembly or loaded from an external file. Finally, the Text property represents the text displayed by the tooltip. Both the icon and the tooltip text can be changed at any time and the modification is promptly reflected in the system's tray.

The following code is all that an application needs to have an icon displayed in the tray area:

trayIcon.Visible = true;

trayIcon.Icon = resources.GetObject("trayIcon.Icon");

trayIcon.Text = "Hi there!";

Place these lines in the Load event handler of the form and compile. When the application starts up, the icon is correctly displayed in the TNA, but the main form of the application is visible.

For most applications that work in the background (i.e., monitoring a port or a system resource), the main form and the tray icon are mutually exclusive. An application resorts to a tray icon if it reckons a full-blown window would be overkill. On the other hand, an application with a regular user interface doesn't often need a tray icon. However, both statements should be taken with a grain of salt because both have a few exceptions. If the background application doesn't need any user interaction, it can work completely hidden from view. If the application is expected to stay minimized most of the time but performs a task repeatedly (i.e., Outlook Express), a tray icon is useful to quickly notify the user when something has happened.

To manage tray icons, you must also know how to work with hidden windows. The most effective way to obtain a perfectly working, but hidden, window is setting the window state to Minimized and the ShowInTaskBar property to False:

this.ShowInTaskBar = false;

this.WindowState = FormWindowState.Minimized;

As a result, no window is displayed upon startup and the specified icon is added to the tray area. The next step is setting up a sort of communication protocol between the user and the application. The icon in the TNA is the only point of contact possible. Before I dig this out, though, a look at some implementation details is in order. Let's briefly compare the parameters you need to pass to the unmanaged Shell_NotifyIcon function and the parameters that the .NET Framework actually requires you to indicate. You'll be surprised to see how many little tasks the .NET Framework implementation of tray icons shaves off.

Implementation Details

The Shell_NotifyIcon Win32 API function has the following signature:

BOOL WINAPI Shell_NotifyIcon(

DWORD dwMsg,

PNOTIFYICONDATA pnid);

The dwMsg parameter indicates the action to take on the icon through mnemonic constants. It can be any of the following basic actions: add, delete, or modify. The pointer to the NOTIFYICONDATA structure gathers information about the surrounding environment. In particular, you are required to indicate the handle of the window that will receive notification messages from the icon; the icon ID, which is a user-defined value that the caller uses to identify the icon uniquely; and the ID of the Windows message that the function will use to pass events on to the notification window.

In summary, the core activity of a tray icon is to display a little bitmap, a context menu, and a tooltip in a particular area of the desktop. For this to happen, a helper window and a couple of unique IDs are needed. If you write a Win32 tray application, you must take care of this yourself. If you write a .NET Framework tray application, you can focus on key things and leave the rest up to the built-in infrastructure.

The icon ID is initialized to 0 in the class constructor. In the same context, an invisible notification window is created and set up to handle mouse messages. The custom Windows message is set to 0x800 and is mostly used to carry out mouse messages. The following code snippet, excerpted from a Win32 tray program, shows how this would normally work.

// 0x800 is WM_TRAYMOUSEMESSAGE

// iconID is the internal ID

case WM_TRAYMOUSEMESSAGE:

if (wParam != iconID)

break;

switch(lParam) {

case WM_RBUTTONUP:

:

case WM_LBUTTONUP:

:

}

When the user right-clicks the icon, a context menu is commonly displayed. This occurs in response to the WM_RBUTTONUP message.

Define the Context Menu

The context menu is created as an HMENU handle in Win32 and as an instance of the ContextMenu component in the .NET Framework. You can populate the ContextMenu object either declaratively in the Visual Studio .NET designer or programmatically using the MenuItems collection of the class. When you're done, you assign it to the ContextMenu property of the NotifyIcon class.

MenuItem m1 = new MenuItem("&Show");

cxMenu.MenuItems.Add(m1);

MenuItem m2 = new MenuItem("E&xit");

cxMenu.MenuItems.Add(m2);

trayIcon.ContextMenu = cxtMenu;

The .NET Framework wrapper for the tray icon automatically handles the WM_RBUTTONUP message and displays the associated context menu. You should note that the ContextMenu class has a Show method to pop the menu up. However, this method requires that you pass in the source control (the control for which the menu is being displayed) and a pointer. As mentioned earlier, the tray icon component is not an instance of a Windows Forms control, meaning that you can't easily display the context menu in response to another mouse event. There are some tray applications (i.e., Microsoft ActiveSync) that display the context menu if you click on the icon whether you use the left or right button. Coding this feature is straightforward in Win32 but requires a bit of explicit interop stuff if done from within a .NET application.

Define Event Handlers

The NotifyIcon component wraps the typical mouse events (i.e., mouse-up, mouse-down, double-click) into more comfortable events. Click, MouseDown, and DoubleClick are the main events the component fires during its lifetime. In addition, a fourth, less interesting, mouse-related event is supported — MouseMove. (Honestly, I can't imagine a reasonable use for this message in a tray application but, in any case, it's there should you ever need it.)

MouseDown is marked as the default event of the NotifyIcon component. The Visual Studio .NET designer automatically adds a handler for it when you double-click the component's icon in the form's tray area — the area below the form in which Visual Studio .NET places UI-less Windows Forms components. It goes without saying that the mouse-down event is different from click and double-click events. In particular, pay attention to the fact that mouse-down fires whenever a mouse button is pressed. The event fires both in case of single and double clicking regardless of whether you use the left or right button.

A good practice is associating a dialog box with the default item of the context menu and the double-click event of the NotifyIcon component. The Click event is ignored or bound to the context menu (more on this in a moment). Listing 1 shows the most significant code of the sample tray application. (The source is available online.) It assumes a context menu with two items — Activate and Exit (see Figure 1). When you click the Activate menu, a dialog box is displayed to perform the tasks the application is designed for. The Exit menu item terminates the application. The DoubleClick event calls the event handler of the Activate event. In the Click event handler, I would display the context menu.

The ContextMenu class has a Show method with the following prototype:

public void Show(Control control, Point pos);

The first argument specifies the control with which this context menu is associated. The second argument specifies the coordinates at which to display the menu. These coordinates are relative to the client area of the control. To display the context menu, close the tray icon and indicate the NotifyIcon component as the argument of type Control. If you do this, though, an invalid cast error is raised because the NotifyIcon component cannot be cast to a Windows Forms control. The question now is: How can the .NET Framework code display the context menu? The answer is in the pseudocode shown in Listing 2.

The pseudocode represents a summary of what the NotifyIcon class does when the user right-clicks on the icon. It calls down to some Win32 API functions such as GetCursorPos and TrackPopupMenuEx. However, the big issue with that code is that it makes extensive use of the tray icon's notification window. For the popup menu to work, you need to call SetForegroundWindow and post a dummy message (see KB 135788). In both cases, you need to pass the handle of the window responsible for the tray icon's message handling. Unfortunately, this window handle (an HWND type in Win32, an IntPtr type in the managed world) is not accessible due to its protection level — it is a private member of the NotifyIcon class. For this reason, you can't reasonably reproduce the code in Listing 2 in your own application. But there is a workaround: using reflection.

The pseudocode in Listing 2 describes the behavior of a real private method of the NotifyIcon class — ShowContextMenu. Using reflection, you can sometimes invoke a private member of a class. (That mostly depends on security settings, but in this case, it just works.)

Type t = typeof(NotifyIcon);

MethodInfo mi = t.GetMethod("ShowContextMenu",

BindingFlags.NonPublic|BindingFlags.Instance);

mi.Invoke(trayIcon, null);

You use the GetMethod method on the Type object that represents the NotifyIcon class to retrieve the method information. By specifying the BindingFlags.NonPublic flag, you also include private and protected methods in the search. The BindingFlags.Instance flag indicates that we're looking for instance (as opposed to static) members. Once a valid instance of the MethodInfo class has been returned, you call its Invoke method specifying the object instance (the trayIcon component) and the list of arguments. The last line logically evaluates to:

trayIcon.ShowContextMenu();

Associate this code with the Click event and you're now displaying the context menu with a simple click.

The Taskbar Created Event

Finally, the NotifyIcon class also has an extra feature that fixes a bug in the Win32 code. The tray icons disappear if, for some reason, the taskbar is restarted. This typically happens if a serious failure occurs in explorer.exe. When the shell is not responding, the operating system can restart it, and explorer.exe recreates the taskbar. When this happens, though, some icons are lost, especially icons added by custom applications. The point is that the operating system (including the most recent Windows 2003 Server) doesn't cache the tray icons, so it is unable to restore them all when the shell restarts. To partially remedy this, the operating system fires a little-known message, named "TaskbarCreated," to all windows. If the notification window catches this message and refreshes the icon, the bad effect of losing tray icons ends. The NotifyIcon class handles this message internally and completely hides from the developer this nasty behavior of the system shell.

For more information on tray applications, you might want to take a look at my e-book Windows Shell Programming, from Wrox Press. w::d