CTrayNotifyIcon v1.4

Welcome to CTrayNotifyIcon, A freeware MFC class to encapsulate the tray notification API in 95,98 and NT 4.

Features
Usage
History
API Reference
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

Usage

- As of v1.4 of CTrayNotifyIcon, the code now makes use of another of the authors classes namely CHookWnd. Before you can compile CTrayNotifyIcon, you will also need to download the CHookwnd source and copy over the hookwnd cpp and h files into the directory where you have unzipped the CTrayNotifyIcon code
- To use the class in your code simple include ntray.cpp and hookwnd.cpp in your project and #include ntray.h in which ever of your modules needs to make calls to the class.
- 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.

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 acomplished 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.

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 the following public functions of the class CTrayNotifyIcon

CTrayNotifyIcon::CTrayNotifyIcon
CTrayNotifyIcon::~CTrayNotifyIcon
CTrayNotifyIcon::Create
CTrayNotifyIcon::SetTooltipText
CTrayNotifyIcon::GetTooltipText
CTrayNotifyIcon::SetIcon
CTrayNotifyIcon::SetStandardIcon
CTrayNotifyIcon::GetIcon
CTrayNotifyIcon::UsingAnimatedIcon
CTrayNotifyIcon::SetNotificationWnd
CTrayNotifyIcon::GetNotificationWnd
CTrayNotifyIcon::HideIcon
CTrayNotifyIcon::ShowIcon
CTrayNotifyIcon::RemoveIcon
CTrayNotifyIcon::MoveToExtremeRight
CTrayNotifyIcon::SetMenu
CTrayNotifyIcon::GetMenu
CTrayNotifyIcon::OnTrayNotification
CTrayNotifyIcon::IsShowing
CTrayNotifyIcon::IsHidden
CTrayNotifyIcon::LoadIconResource

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);

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

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.

Remarks

Creates a tray notification icon.

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(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.

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

CTrayNotifyIcon::ShowIcon

void CTrayNotifyIcon::ShowIcon();

Remarks

Shows the icon if it had previously been hidden

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::MoveToExtremeRight

void MoveToExtremeRight();

Remarks

Moves the tray icon to the extreme right of the tray notification area. This is achieved by first hiding the icon followed by re showing it.

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. NOTTEST 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.

CONTACTING THE AUTHOR

PJ Naughter
Email: pjn@indigo.ie
Web: http://indigo.ie/~pjn
16 May 1999