NTRAY port to WTL (based on CTrayNotifyIcon v1.55)

zhaozg

4.53/5 (7 votes)

Aug 12, 2006

19 min read

74741

1363

CTrayNotifyIcon is a great and easy tool, make a portable copy to WTL.

Sample Image - wtlntray.jpg

Introduction

Thank PJ Naughter firstly, The original CTrayNotifyIcon is on http://www.naughter.com/ntray.html. I just only changed some code from MFC to WTL.

CTrayNotifyIcon hides a lot of the drudgery of calling the API directly and provides a nice clean C++ interface to using it. Overloaded member functions are provided to set and get the ToolTip text, icon and notification window. The class also provides a default implementation to bring up a context menu and provides a default menu item which is executed when you double click the icon. The class also provides auto cleanup and resurrection of icons if the shell unexpectedly crashes.

WTL port version keeps all interface unchanged, So you can read CTrayNotifyIcon document.

Good Message from PJ Naughter at http://www.naughter.com/ntray.html: Updated the code to operate independent of MFC if so desired. This requires WTL which is an open source library extension for ATL to provide UI support along the lines of MFC. So nice man!
Who want to use this package should download from http://www.naughter.com/ntray.html,all credit belong to PJ Naughter.

CTrayNotifyIcon v1.55

Welcome to CTrayNotifyIcon, A freeware MFC class to encapsulate the tray notification API on Windows.

Contacting the Author

Features

Simple and clean C++ interface.
The classes are fully Unicode compliant and include Unicode built options in the workspace file.
All code compiles cleanly at warning level 4.
Supports all of the tray functionality right up to Windows XP SP2, while at the same time, the class will work without problems on versions of Windows as far back as Windows 95 Gold. Of course if you want to use new features such as balloon tray icons etc, then this functionality will of course be only available on later versions of Windows, so you still may need to handle this issue in your client application if you still support older versions of Windows.
Hides the complexity of having to deal with the messy NOTIFYICONDATA structure and all its various quirks, which you probably will be familiar with if you have coded directly to the "Shell_NotifyIcon" API.

Usage

To use the class in your code simple include NTray.cpp in your project and #include NTray.h in which ever of your modules needs to make calls to the class.
You will need an up to date Platform SDK installed to compile the code if you are using Visual C++ 6 (February 2003 was the last version which was compatible with VC 6).
As of v1.51, the code now uses ATL's CWindowImpl class in preference to the author's CHookWnd class. This does mean that for MFC only client projects, you will need to add ATL support to your project.
To see the class in action, have a look at the code in the module "mainfrm.cpp".
Your code will need to include MFC either statically or dynamically.

Copyright

You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

v1.0 (14 May 1997)

Initial Public release.

v1.1 (25 November 1997)

Addition of HideIcon(), ShowIcon() & MoveToExtremeRight()
Support for animated tray icons

v1.2 (23 June 1998)

Class now supports the new Taskbar Creation Notification message which comes with IE 4. This allows the tray icon to be recreated whenever the explorer restarts (Crashes!!)

V1.3 (22 July 1998)

Code now compiles cleanly at warning level 4
Code is now UNICODE enabled + build configurations are provided
The documentation for the class has been completely revamped

V1.31 (27 January 1999)

Code now correctly loads up 16*16 icons, previously it allowed Windows to rescale the icon from 32*32 resulting in slightly blurry images. This has been accomplished via the new LoadIconResource method.

V1.32 (28 January 1999)

Removed a number of level 4 warnings which were occurring.

V1.33 (9 May 1999)

Fixed a problem as documented in KB article "PRB: Menus for Notification Icons Do Not Work Correctly", Article ID: Q135788.

V1.4 (16 May 1999)

Modified the sample program to ensure that 16*16 icons are used when tray icon animation is not being used.
Now uses the author's hookwnd class. This prevents the need to create the two hidden windows namely CTrayRessurectionWnd and CTrayTimerWnd to handle icon animation and tray creation messages.
Sample project now compiles at warning level 4.
General code tidy up and rearrangement.
Added numerous ASSERT's to improve the code's robustness.
Added functions to allow context menu to be customized.

21 May 2000

Minor update to the documentation.

V1.41 (1 January 2001)

Now includes copyright message in the source code and documentation.
Fixed problem where the window does not get focus after double clicking on the tray icon.
Now fully supports the Windows 2000 balloon style tooltips.
Fixed a off by one problem in some of the ASSERT's.
Fixed problems with Unicode build configurations.
Provided Win2k specific build configurations.

V1.42 (10 February 2001)

Now fully supports creation of 2 tray icons at the same time.

V1.43 (13 June 2001)

Now removes windows hook upon call to RemoveIcon.

V1.44 (26 August 2001)

Fixed memory leak in RemoveIcon.
Fixed GPF in RemoveIcon by removing call to Unhook

V1.45 (28 August 2001)

Added support for direct access to the System Tray's HDC. This allows you to generate an icon for the tray on the fly using GDI calls. The idea came from the article by Jeff Heaton in the April issue of WDJ. Also added are overridden Create methods to allow you to easily construct a dynamic tray icon given a BITMAP instead of an ICON.

25 November 2002

Added a comment to the NTray.h header file about where to get the HookWnd.h file if the code compile fails.

V1.46 (21 March 2003)

Fixed icon resource leaks in SetIcon(LPCTSTR lpIconName) and SetIcon(UINT nIDResource). Thanks to Egor Pervouninski for reporting this.
Fixed unhooking of the tray icon when the notification window is being closed.

V1.47 (31 March 2003)

Now uses V1.05 of my Hookwnd class

V1.48 (2 April 2003)

Now uses v1.06 of my Hookwnd class
Fixed a bug in the sample app for this class where the hooks should have been created as global instances rather than as member variables of the mainframe window. This ensures that the hooks remain valid even after calling DefWindowProc on the mainframe.

V1.49 (23 July 2004)

Minor update to remove unnecessary include of "resource.h"

V1.50 (3 March 2006)

Updated copyright details.
Updated the documentation to use the same style as the web site.
Did a spell check of the documentation.
Fixed some issues when the code is compiled using /Wp64. Please note that to support this the code now requires a recentish Platform SDK to be installed if the code is compiled with Visual C++ 6.
Replaced all calls to ZeroMemory with memset.
Fixed an issue where SetBalloonDetails was not setting the cbSize parameter. Thanks to Enrique Granda for reporting this issue.
Added support for NIIF_USER and NIIF_NONE flags.
Now includes support for NIM_NIMSETVERSION via SetVersion. In addition this is now automatically set in the Create() calls if the Win2k boolean parameter is set.
Removed derivation from CObject as it was not really needed.
Now includes support for NIM_SETFOCUS
Added support for NIS_HIDDEN via the ShowIcon and HideIcon methods.
Added support for NIIF_NOSOUND

V1.51 (27 June 2006)

Code now uses new C++ style casts rather than old style C casts where necessary.
The class framework now requires the Platform SDK if compiled using VC 6.
Updated the logic of the ASSERTs which validate the various string lengths.
Fixed a bug in CTrayNotifyIcon::SetFocus() where the cbSize value was not being set correctly.
CTrayIconHooker class now uses ATL's CWindowImpl class in preference to the author's CHookWnd class. This does mean that for MFC only client projects, you will need to add ATL support to your project.
Optimized CTrayIconHooker constructor code.
Updated code to compile cleanly using VC 2005. Thanks to "Itamar" for prompting this update.
Addition of a CTRAYNOTIFYICON_EXT_CLASS and CTRAYNOTIFYICON_EXT_API macros which makes the class easier to use in an extension dll.
Made CTrayNotifyIcon destructor virtual.

V1.52 (3 July 2006)

Fixed a bug where the HideIcon functionality did not work on Windows 2000. This was related to how the cbSize member of the NOTIFYICONDATA structure was initialized. The code now dynamically determines the correct size to set at runtime according to the instructions provided by the MSDN documentation for this structure. As a result of this, all "bWin2k" parameters which were previously exposed via CTrayNotifyIcon have now been removed as there is no need for them. Thanks to Edwin Geng for reporting this important bug. Client code will still need to intelligently make decisions on what is supported by the OS. For example balloon tray icons are only supported on Shell v5 (nominally Windows 2000 or later). CTrayNotifyIcon will ASSERT if for example calls are made to it to create a balloon tray icon on operating systems with < Shell v5.

V1.53 (5 July 2006)

Fixed a bug where the menu may pop up a second time after a menu item is chosen on Windows 2000. The problem was tracked down to the code in CTrayNotifyIcon::OnTrayNotification. During testing of this bug, I was unable to get a workable solution using the new shell messages of WM_CONTEXTMENU, NIN_KEYSELECT & NIN_SELECT on Windows 2000 and Windows XP. This means that the code in CTrayNotifyIcon::OnTrayNotification uses the old way of handling notifications (WM_RBUTTDOWN*). This does mean that by default, client apps which use the CTrayNotifyIcon class will not support the new keyboard and mouse semantics for tray icons (IMHO this is no big loss!). Client code is of course free to handle their own notifications. If you go down this route then I would advise you to thoroughly test your application on Windows 2000 and Windows XP as my testing has shown that there is significant differences in how tray icons handle their messaging on these 2 operating systems. Thanks to Edwin Geng for reporting this issue.
Class now displays the menu based on the current message's screen coordinates, rather than the current cursor screen coordinates.
Fixed bug in sample app where if the about dialog is already up and it is reactivated from the tray menu, it did not bring itself into the foreground

V1.54 (6 July 2006)

Reverted the change made for v1.53 where the screen coordinates used to show the context menu use the current message's screen coordinates. Instead the pre v1.53 mechanism which uses the current cursor's screen coordinates is now used. Thanks to Itamar Syn-Hershko for reporting this issue.

V1.55 (19 July 2006)

The default menu item can now be customized via SetDefaultMenuItem and GetDefaultMenuItem. Thanks to Mikhail Bykanov for suggesting this nice update.
Optimized CTrayNotifyIcon constructor code

API Reference

Instantiate a CTrayNotifyIcon where it will be around for the lifetime of your icon. The sample program does this in the mainframe as the icon will be available for the lifetime of the application. In the sample program this is done in the mainframe class. The API consists of the following public functions of the class CTrayNotifyIcon

CTrayNotifyIcon::CTrayNotifyIcon

CTrayNotifyIcon::CTrayNotifyIcon();

Remarks

Standard constructor, just initialises all member variables to safe values.

CTrayNotifyIcon::~CTrayNotifyIcon

CTrayNotifyIcon::~CTrayNotifyIcon();

Remarks

Standard destructor. Internally this will call RemoveIcon to remove the icon from the UI.

CTrayNotifyIcon::Create

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT nID, LPCTSTR pszTooltipText, HICON hIcon, UINT nNotifyMessage, UINT uMenuID=0);

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT uID, LPCTSTR pszTooltipText, HICON* phIcons, int nNumIcons, DWORD dwDelay, UINT nNotifyMessage, UINT uMenuID=0);

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT uID, LPCTSTR pszTooltipText, LPCTSTR pszBalloonText, LPCTSTR pszBalloonCaption, UINT nTimeout, BalloonStyle style, HICON hIcon, UINT nNotifyMessage, UINT uMenuID=0, BOOL bNoSound = FALSE);

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT uID, LPCTSTR pszTooltipText, LPCTSTR pszBalloonText, LPCTSTR pszBalloonCaption, UINT nTimeout, BalloonStyle style, HICON* phIcons, int nNumIcons, DWORD dwDelay, UINT nNotifyMessage, UINT uMenuID=0, BOOL bNoSound = FALSE);

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT uID, LPCTSTR pszTooltipText, CBitmap* pBitmap, UINT nNotifyMessage, UINT uMenuID=0);

BOOL CTrayNotifyIcon::Create(CWnd* pNotifyWnd, UINT uID, LPCTSTR pszTooltipText, LPCTSTR pszBalloonText, LPCTSTR pszBalloonCaption, UINT nTimeout, BalloonStyle style, CBitmap* pBitmap, UINT nNotifyMessage, UINT uMenuID=0, BOOL bNoSound = FALSE);

Return Value

TRUE if the tray icon was successfully created otherwise FALSE.

Parameters

pNotifyWnd: The window to send notification messages to. This can be changed later by using the SetNotificationWnd method.

uID: An application defined value to associate with each tray icon. This allows you to display multiple icons from one app. CTrayNotifyIcon also overrides its meaning such that it is used as the menu resource id for the context menu.

pszTooltipText: Initial tooltip text to display. This can be changed later using the SetTooltipText method.

hIcon: The icon to display. This can be changed later using the SetIcon method.

nNotifyMessage: This is the notification message to use to inform the window about mouse messages. This should be defined as some WM_USER message and handled in the notification windows message map using the ON_MESSAGE macro. To see how to hook this up have a look at the mainfrm.cpp

phIcons: pointer to an array of icon handles to use to do the icon animation.

nNumIcons: The number of icons phIcons points to.

dwDelay: interval in milliseconds between icon animation frames.

pszBalloonText: The text to appear in the balloon style tooltip

pszBalloonCaption: The caption for the balloon style tooltip

nTimeout: The timeout associated with the balloon style tooltip. After this time (in milliseconds) the balloon tooltip will disappear.

style: The icon to appear in the balloon tooltip. It can be one of the enum values CTrayNotifyIcon::Info, CTrayNotifyIcon::Error, CTrayNotifyIcon::Warning, CTrayNotifyIcon::None or CTrayNotifyIcon::User. Please note that CTrayNotifyIcon::User is only available on XP SP2 or later. Also note that Balloon style tooltips themselves are only available on version 5 of the shell or later (Windows 2000 or later).

uMenuID Set this value to a non-zero value to use a different menu resource instead of the default one as specified by uID

pBitmap The bitmap to display as the icon. Internally the code converts the bitmap to an icon prior to displaying it.

bNoSound Setting this value to TRUE (the default is FALSE) will cause the shell not to play the popup sound when the balloon style tooltip is shown. Please note that this functionality is only available on XP SP2 or later.

Remarks

Creates a tray notification icon. The 2 overridden versions which specify balloon tooltips are only available on Shell v5 (nominally Windows 2000 and later).

CTrayNotifyIcon::SetTooltipText

BOOL CTrayNotifyIcon::SetTooltipText(LPCTSTR pszTooltipText);

BOOL CTrayNotifyIcon::SetTooltipText(UINT nID);

Return Value

TRUE if the tooltip text was changed successfully otherwise FALSE

Parameters

pszTooltipText The text to set

nID A windows string resource ID of the text to set

Remarks

Sets the tooltip text associated with the tray icon

CTrayNotifyIcon::GetTooltipText

CString CTrayNotifyIcon::GetTooltipText() const

Return Value

The current tooltip text

CTrayNotifyIcon::SetIcon

BOOL SetIcon(HICON hIcon);

BOOL SetIcon(CBitmap* pBitmap);

BOOL SetIcon(LPCTSTR lpIconName);

BOOL SetIcon(UINT nIDResource);

BOOL SetIcon(HICON* phIcons, int nNumIcons, DWORD dwDelay);

Return Value

TRUE if the icon was changed successfully otherwise FALSE

Parameters

hIcon handle to the icon to set

lpIconName a Windows Icon resource string of the icon to use

nIDResource a Windows Icon resource ID of the icon to use

phIcons: pointer to an array of icon handles to use to do the icon animation.

nNumIcons: The number of icons phIcons points to.

dwDelay: interval in milliseconds between icon animation frames.

pBitmap The bitmap to use as the icon

Remarks

Sets the icon associated with the tray icon. Normally you should use LoadIconResource to load up your icons.

CTrayNotifyIcon::SetStandardIcon

BOOL CTrayNotifyIcon::SetStandardIcon(LPCTSTR lpIconName);

BOOL CTrayNotifyIcon::SetStandardIcon(UINT nIDResource);

Parameters

lpIconName a Windows Icon resource string of the icon to use

nIDResource a Windows Icon resource ID of the icon to use

Remarks

Sets the icon associated with the tray icon using the standard icon identifiers.

To use one of the Windows predefined icons, the lpIconName parameter to one of the following values:

Value	Description
IDI_APPLICATION	Default application icon.
IDI_ASTERISK	Same as IDI_INFORMATION.
IDI_ERROR	Hand-shaped icon.
IDI_EXCLAMATION	Same as IDI_WARNING.
IDI_HAND	Same as IDI_ERROR.
IDI_INFORMATION	Asterisk icon.
IDI_QUESTION	Question mark icon.
IDI_WARNING	Exclamation point icon.
IDI_WINLOGO	Windows logo icon.

CTrayNotifyIcon::GetIcon

HICON CTrayNotifyIcon::GetIcon() const;

Return Value

Icon handle of the icon currently being displayed

CTrayNotifyIcon::UsingAnimatedIcon

BOOL UsingAnimatedIcon() const;

Return Value

TRUE if an animated icon is being show, FALSE if an ordinary static icon is being used.

CTrayNotifyIcon::SetNotificationWnd

BOOL CTrayNotifyIcon::SetNotificationWnd(CWnd* pNotifyWnd);

Return Value

TRUE if the notification window was successfully set otherwise FALSE

Parameters

pNotifyIcon The window which is to be the notification window associated with this tray icon

CTrayNotifyIcon::GetNotificationWnd

CWnd* GetNotificationWnd() const;

Return Value

The window which is the notification window associated with this tray icon

CTrayNotifyIcon::HideIcon

void CTrayNotifyIcon::HideIcon();

Remarks

Temporarily hides the tray notify icon. If the class detects that it is running on Shell v5 or later (nominally Windows 2000 or later, then this method will use the NIS_HIDDEN functionality to hide the icon as opposed to actually destroying the tray icon. Using this feature means that the position of the re-shown icon is preserved instead of it appearing on the extreme left when it is fully recreated.

CTrayNotifyIcon::ShowIcon

void CTrayNotifyIcon::ShowIcon();

Remarks

The corollary function to HideIcon

CTrayNotifyIcon::RemoveIcon

void CTrayNotifyIcon::RemoveIcon();

Remarks

Removes the tray icon entirely and resets the class member variables. This is the corollary function of CTrayNotifyIcon::Create

CTrayNotifyIcon::SetMenu

void CTrayNotifyIcon::SetMenu(HMENU hMenu);

Parameters

hMenu The menu resource to use as the context menu for the tray icon.

CTrayNotifyIcon::GetMenu

CMenu& CTrayNotifyIcon::GetMenu();

Return Value

menu resource currently associated with the tray icon.

CTrayNotifyIcon::OnTrayNotification

virtual LRESULT CTrayNotifyIcon::OnTrayNotification(WPARAM uID, LPARAM lEvent);

Return Value

Standard result to return from the message handler

Parameters

uID: the value you specified in the call to CTrayNotifyIcon::Create

lEvent: is a mouse event (such as WM_LBUTTONDOWN).

Remarks

When your handler gets control, WPARAM is the ID you specified when you created the CTrayNotifyIcon. LPARAM is the mouse event (for example,WM_LBUTTONDOWN). You can do whatever you like when you get the notification. The provided sample app does nothing and delegates all the work to the default implementation in CTrayNotifyIcon This virtual (so you can override it) function implements the default UI behaviour as outlined in the "Windows Interface Guidelines for Software".

CTrayNotifyIcon::IsShowing

BOOL CTrayNotifyIcon::IsShowing() const;

Return Value

TRUE if the tray icon is currently been shown else FALSE

CTrayNotifyIcon::IsHidden

BOOL CTrayNotifyIcon::IsHidden();

Return Value

TRUE if the tray icon is currently hidden else FALSE

CTrayNotifyIcon::LoadIconResource

static HICON CTrayNotifyIcon::LoadIconResource(LPCTSTR lpIconName);

static HICON CTrayNotifyIcon::LoadIconResource(UINT nIDResource);

Parameters

lpIconName a Windows Icon resource string of the icon to load

nIDResource a Windows Icon resource ID of the icon to load

Return Value

An icon handle if the icon could be loaded otherwise NULL.

Remarks

You should call this function in preference to the MFC CWinApp::LoadIcon or SDK LoadIcon call to load up your icons for use by CTrayNotifyIcon. This function will first attempt to load a 16*16 size icon. Normally when you ask Windows to load up an icon, it will first try to load it as a 32*32 resource, then Windows will scale it down to 16*16 for use in the tray often resulting in slightly blurred images.

CTrayNotifyIcon::SetBalloonDetails

BOOL CTrayNotifyIcon::SetBalloonDetails(LPCTSTR pszBalloonText, LPCTSTR pszBalloonCaption, BalloonStyle style, UINT nTimeout, HICON hUserIcon=NULL, BOOL bNoSound=FALSE);

Return Value

TRUE if the details were updated successfully otherwise FALSE

Parameters

pszBalloonText: The text to appear in the balloon style tooltip

pszBalloonCaption: The caption for the balloon style tooltip

nTimeout: The timeout associated with the balloon style tooltip. After this time (in milliseconds) the balloon tooltip will disappear

style: The icon to appear in the balloon tooltip. Please see CTrayNotifyIcon::Create for more details on the possible values.

hUserIcon: If you set "style" to User, then this parameter is where you specify the user icon to display in the balloon style tooltip

bNoSound: Setting this value to TRUE (the default is FALSE) will cause the shell not to play the popup sound when the balloon style tooltip is shown. Please note that this functionality is only available on XP SP2 or later

Remarks

Sets the balloon tooltip details associated with the tray icon

CTrayNotifyIcon::GetBalloonText

CString CTrayNotifyIcon::GetBalloonText() const

Return Value

The current balloon text

CTrayNotifyIcon::GetBalloonCaption

CString CTrayNotifyIcon::GetBalloonCaption() const

Return Value

The current balloon caption

CTrayNotifyIcon::GetBalloonStyle

CTrayNotifiyIcon::BalloonStyle CTrayNotifyIcon::GetBalloonStyle() const

Return Value

The current style balloon tooltip being used

CTrayNotifyIcon::GetBalloonTimeout

UINT CTrayNotifyIcon::GetBalloonTimeout() const

Return Value

The current timeout (in milliseconds) associated with the balloon tooltip being used

CTrayNotifyIcon::BitmapToIcon

HICON CTrayNotifyIcon::BitmapToIcon(CBitmap* pBitmap)

Return Value

An ICON representation of the specified bitmap

Parameters

pBitmap: The bitmap to convert to an icon

Remarks

Converts a windows bitmap to a icon. This method is used by the Create method when called with a CBitmap instead of a HICON.

CTrayNotifyIcon::GetDynamicDCAndBitmap

static BOOL CTrayNotifyIcon::GetDynamicDCAndBitmap(CDC* pDC, CBitmap* pBitmap)

Return Value

TRUE if the DC and bitmap were obtained ok otherwise FALSE

Parameters

pDC: The address of a DC class to be returned with a DC compatible with the tray.

pBitmap: The address of a bitmap which will contain the tray icon representation.

Remarks

This function should be called in preparation for using dynamic tray icons (i.e. where you construct the ICON at runtime by drawing into a memory device context.). Upon a successful return you should hang on to these two parameters until you need them. For example in the sample app, the code periodically updates the DC by drawing a new number into the DC and then updating the tray icon with this. For more info on using dynamic tray icons, please consult the supplied sample application.

CONTACTING THE AUTHOR

PJ Naughter
Email: pjna(at)naughter.com
Web: http://www.naughter.com
19 July 2006