Using the System Tray in VB

This project requires the use of the component library Microsoft Windows Common Controls 5.0 or 6.0. To add one of these to your project go to Project->Components and select the library from the list. We will be creating a standard exe project with a form and a module file.

VB (as of version 6) has no built in support for using the system tray, so we will have to resort to using what is known as the Windows API. An API is an Application Programming Interface - this is essentially a list of all of the functions and methods that are available to us, in this case under Windows. To add a system tray icon, we need to use one of these functions: Shell_NotifyIconA(). To use this function in VB add a module file to your project called modSystemTray and add the code:

This probably requires some more explanation. Shell_NotifyIcon() is the function that we use to interact with the system tray. Its first argument is one of NIM_ADD,. NIM_MODIFY and NIM_DELETE, telling the function what we want to do to the icon in question. The second argument describes the icon that we are going to perform the operation on.

So, on to adding an icon. Add a command button called cmdAddIcon to your form (which I am assuming is called frmSystray) and the add this code to the form:

The flags in nid.uFlags are used to indicate which data is valid. This means that later on if we wanted to change just the tooltip then we would set nid.uFlags = NIF_TIP and Shell_NotifyIconA would know to only look at szTip, not hIcon or uCallbackMessage.

You can run this program as is, although it is not really good practise - we should really remove the icon from the tray as well when the program ends.

Because we only have one function for the system tray, removing an icon is very similar to adding an icon. Add a command button called cmdRemoveIcon to your form and then add the following code:

You may also wish to add this line to the end of AddTrayIcon():

You may have noticed that the icon will be removed twice if we have removed the icon manually by clicking on cmdRemoveIcon and then go on to quit the program. This is not a problem as Shell_NotifyIconA will just return an error but do nothing more. On success, Shell_NotifyIconA returns a 1. On error it returns 0.

Note also the use of Me. Me refers to the current object - within a form it will refer to that form.

So far we have just been using a single icon. If we want to use more than one icon available in the system tray (either to have multiple icons, or to use dirrent images on a single icon) what can we do? I can think of three solutions. The first, as tends to happen, is easy but not very good - we could add further forms to our project and give them the necessary icons. This is bad because our program will quickly grow in size with each new form added. It is also extremely untidy and inelegant. The second solution is probably my preferred solution and involves the use of an ImageList control from the Microsoft Windows Common Controls library.

Add an ImageList called ilstIcons to your form and select it. In the properties list on the right hand side, you should be able to see an entry "(Custom)". Select this item and click the button that appears. This should bring up the Property Pages for the ImageList (property pages will be covered in a later tutorial). To add some icons to the ImageList, select size as 16 x 16 then go to the Images tab. Click "Insert Picture" to add icons to the list - make sure that *.ico is shown in the file filter box. It is now possible to access this icon with eg.

This will return a handle to the first icon held in the ImageList.

The third method delves into the Windows API once more to load the icons at run time. This method would be useful for allowing user defined tray icons. Add the following code to modSystray:

LoadImage() can be used to load a number of different types of images - most important for us, it can load icons. DeleteObject() is used to free all resources associated with an object - the icon image in our case.

We need to be able to specify what type of image to load (the argument dwImageType in LoadImage):

Lastly, we need to specify that the icon should be loaded from a file (the argument dwFlags in LoadImage):

Unfortunately, LR_LOADFROMFILE is not supported in Windows NT.

To use LoadImage we would enter the following:

Where hIcon is the memory address of the loaded icon, IconPath is the path of the icon we wish to load and 16 gives the dimensions of the icon.

When we have finished with the icon, we must delete it to free up the memory it uses:

Now that we have more than one icon available to our project it is time to look at modifying our dray icon. A not uncommon use of modifying the tray icon is to flash the icon to indicate to the user that there is something for their attention. We will look at how this can be done. I have created a completely transparent icon for the time when apparently no icon is to be displayed - it is part of the project available for download here.

You can use either of the methods described above for loading the second icon but I am going to use LoadImage as it is a little more complicated and hence better if it is explained in more depth. Both methods are shown in the download.

Add the next lines to the top of frmSystray, just under Option Explicit. This will make them available to all functions in the form. If you do not have an Option Explicit line, you should do! Go to the Tools->Options menu and in the Editor tab make sure that "Require Variable Declaration" is checked. This will add Option Explicit to further forms but you must still add it to any existing forms. Setting this option means that all variables must be declared before they are used which prevents mistyped variables, e.g. typing RecieveBuffer instead of ReceiveBuffer. If Option Explicit is not set, this would go unnoticed and be very hard to debug.

We will use SolidIcon to store whether the solid (opaque) icon is displayed or whether the transparent icon is displayed.

In the Form_Load event add the following line above the AddTrayIcon line:

This requires that the file "trans.ico" is in the same path as our program.

Add

to the end of AddTrayIcon.

Now add a timer control called tmrFlash to frmSystray. In the properties for tmrFlash, set Enabled to False and interval to 500 - this is the rate in milliseconds at which the timer will generate an event.

Add a command button called cmdFlashIcon to the form. In the cmdFlashIcon_Click event add the following code:

Clicking on this button will then enable/disable the timer.

Now to add some code to the timer event.

This is the code that does the work for flashing the icon. Again it is very similar to both adding and deleting icons.

To ensure that the program exits properly if the timer is running, you should add the following line to the Form_Unload event:

All the work we have done so far is very pretty, but not particularly useful. We want to be able to receive information about how the user is interacting with our icon. The events generated by our icon are all sent the window we specified when it was added. At the moment we have no way of processing these events. The method by which we can see these events is known as subclassing. In real terms what this means is that we replace the default window event handler function with one of our own which processes the system tray events and then passes control back to the default function. This is not without risk - if you are running your program within VB and it comes across an error, the window events will no longer be processed because your program has stopped - this makes VB freeze up. Also, in the same scenario if you press the Stop button in VB rather than closing your program properly, it will cause VB to crash. In other words - be careful!

Add the following code to modSystray:

Add these lines to the end of AddTrayIcon:

And these to the end of RemoveTrayIcon:

Now, as the code runs the first part of the new code to be processed will be the new line in AddTrayIcon. SetWindowLongA can be used in a number of different ways, as defined by nIndex. In this case we are using it to change the event handler function. AddressOf is a very useful operator - it returns the address of a function. The function must be in a module though. SetWindowLongA returns the address of the default window handler - we need this later so save it in the global variable OldWindowProc.

When we come to remove the icon, we have no longer any need to process events ourselves and anyway we should reset the window handler before the program quits. This is what the code in RemoveTrayIcon does - sets the window handler back to the default.

So onto the WindowProc function. This function must have the exact arguments as shown because it is called by a Windows function that expects exactly that format. The line of code at the end of the function calls the default window handler and sets the return value of WindowProc to be the return value of CallWindowProcA. You do not need to modify this part in any way - it will be the same for any program that you write using subclassing.

When WindowProc is called, the argument Msg contains the message number of the event that has fired. The only one that we are intererested in, however, is the number that we specified when we added the icon in nid.uCallbackMessage. When this event does occur, the argument lParam will hold the type of event that has happened as in MOUSE_... above and wParam indicates the affected icon - this is the number of the icon that we set in nid.uID.

Select your form and then go to the menu Tools->Menu Editor. Add a menu called mnuSysTray and make it invisible - it does not matter what the caption is. Now add two more items called mnuSysTrayHide and mnuSysTrayShow with captions Hide and Show respectively. For each of these two items, click on the right arrow button so that three dots ... appear before their caption in the list - this means that they belong to mnuSysTray. Add the following code to the form:

We are going to use this as a pop up menu. So, in WindowProc add the following:

Now try running the program and right clicking on the icon that appears.

This concludes my introduction to using the System Tray in VB. The project I created for this tutorial including all tidied up code is available here: Tutorial Files (12KB)