S.I.V.: Simple tray icon implementation

• Download demo project - 18.5 Kb
• Download source - 1.55 Kb

Introduction

Welcome to my second article of Simplicity Is Virtue philosophy. Never heard of it? Of course, I created it.. (-: (If you're really interested what the heck is that, then take a look at my first article.) This article is aimed towards beginners, so all of you coding gurus and wizards can skip all of this. In this article, you can learn how to:

• create, modify and remove a tray icon
• define and use home-made window messages

Before we begin, let me explain why create YET ANOTHER tray icon class, when there are so many of them, free for use. Well, I was browsing the net, searching for a tray icon class, just being lazy of typing my own code. I actually found a whole bunch of them, free, powerful and quite often - loaded with features I don't need. That means - very irritating to use. So I said to myself, Today IS a good day to die, and started coding the most simple tray icon class anyone could ever think of :-). Let us begin.

Preparations

Before we do anything, let us recall: you create a tray icon by creating a NOTIFYICONDATA structure, and giving it to the Shell_NotifyIcon API function. That tends to be quite irritating, especially if you change the icon or the tooltip frequently during runtime. Because of that, we will create a new class, and provide ourselves a simple and clean interface.

First, we create a new dialog based project, all other options are irrelevant. We begin by adding a new generic class to our project. I named mine "CSimpleTray". Now, we will take care of the private class variables: we need a single icon, a single tooltip, and a single NOTIFYICONDATA structure. Besides that, we would need an indicator whether our icon is shown or not, so we will create a BOOL variable called m_bEnabled. The class should look like this by now:

// SimpleTray.h

class CSimpleTray  
{
public:
    CSimpleTray();
    virtual ~CSimpleTray();

private:
    BOOL m_bEnabled;
    HICON m_hIcon;
    NOTIFYICONDATA m_nid;
    CString m_strTooltip;
};

Now let's see: besides showing and hiding the icon, we want to be able to change the icon and tooltip during runtime, and basically that's all we will do here. Simple interface will consist only of these functions:

• void Show();
• void Hide();
• void SetIcon( HICON hIcon );
• void SetTooltip( LPCTSTR lpTooltip );

Still, there is only one thing to think of: we want our icon to actually DO something when our user clicks on it. To implement that, we will make our icon send a notification to the app's main dialog, simply by sending a custom window message. First things first, we will define the message before our tray icon class declaration, like this:

// SimpleTray.h

// at the beggining of the file, before class declaration
#define WM_TRAYNOTIFY WM_APP+1

Now, we need to mess a bit with the dialog itself, add a new protected function declared like this:

afx_msg void OnTrayNotify( WPARAM wParam, LPARAM lParam );

Ok, so now that we have #defined a window message and a function, we need to connect them. You do this by manually adding an entry to the framework's message map:

// TrayDemoDlg.cpp

BEGIN_MESSAGE_MAP(CTrayDemoDlg, CDialog)
    //{{AFX_MSG_MAP(CTrayDemoDlg)
    ON_WM_SYSCOMMAND()
    ON_WM_PAINT()
    ON_WM_QUERYDRAGICON()
    ON_MESSAGE(WM_TRAYNOTIFY, OnTrayNotify) // <-- add this line
    //}}AFX_MSG_MAP
END_MESSAGE_MAP()

Note that there is no semicolon at the end of the line. Now, every time our dialog receives WM_TRAYNOTIFY message, it will call the message we created - OnTrayNotify. Of course, you will need to #include the class declaration file, otherwise the compiler will complain that WM_TRAYNOTIFY is not defined.

// TrayDemoDlg.cpp

// at the beggining of the file
#include "stdafx.h"
#include "TrayDemo.h"
#include "TrayDemoDlg.h"
#include "SimpleTray.h" // <-- this one

Finally - the class..

Finally, we get to code the class. Let us check out the code:

CSimpleTray::CSimpleTray()
{
    // initialize 
    m_hIcon = NULL;
    m_strTooltip = "";
    m_bEnabled = FALSE;
}

CSimpleTray::~CSimpleTray()
{
    Hide(); // a good thing to do :-)
}

void CSimpleTray::Show()
{
    // check to see if we have a valid icon
    if ( m_hIcon == NULL )
        return;

    // make sure we are not already visible
    if ( m_bEnabled == TRUE )
        return;

    // initialize the TRAYNOTIFYDATA struct
    m_nid.cbSize = sizeof(m_nid);

    m_nid.hWnd = AfxGetMainWnd()->m_hWnd; // the 'owner' window
                        // this is the window that
                        // receives notifications
    m_nid.uID = 100;    // ID of our icon, as you can have
                // more than one icon in a single app

    m_nid.uCallbackMessage = WM_TRAYNOTIFY; // our callback message
    strcpy(m_nid.szTip, m_strTooltip); // set the tooltip
    m_nid.hIcon = m_hIcon; // icon to show

    m_nid.uFlags = NIF_MESSAGE | // flags are set to indicate what
            NIF_ICON | // needs to be updated, in this case
            NIF_TIP; // callback message, icon, and tooltip

    Shell_NotifyIcon( NIM_ADD, &m_nid ); // finally add the icon

    m_bEnabled = TRUE; // set our indicator so that we
                // know the current status
}

void CSimpleTray::Hide()
{
    // make sure we are enabled
    if ( m_bEnabled == TRUE )
    {
        // we are, so remove
        m_nid.uFlags = 0;
        Shell_NotifyIcon( NIM_DELETE, &m_nid );
        // and again, we need to know what's going on
        m_bEnabled = FALSE;
    }
}

void CSimpleTray::SetIcon(HICON hIcon)
{
    // first make sure we got a valid icon
    if ( hIcon == NULL )
        return;

    // set it as our private
    m_hIcon = hIcon;

    // now check if we are already enabled
    if ( m_bEnabled == TRUE )
    {   // we are, so update
        m_nid.hIcon = m_hIcon;
        m_nid.uFlags = NIF_ICON; // icon only
        Shell_NotifyIcon( NIM_MODIFY, &m_nid );
    }
}

void CSimpleTray::SetTooltip(LPCTSTR lpTooltip)
{
    // tooltip can be empty, we don't care
    m_strTooltip = lpTooltip;

    // if we are enabled
    if ( m_bEnabled == TRUE )
    {   // do an update
        strcpy(m_nid.szTip, m_strTooltip);
        m_nid.uFlags = NIF_TIP; // tooltip only
        Shell_NotifyIcon( NIM_MODIFY, &m_nid );
    }
}

That's it!

How to use it?

The most simple way would be to use your applications icon, and show the damn thing at the program startup, inside OnInitDialog(). First, add a private variable of type CSimpleTray to the dialog class:

and then use it like this:

// TrayDemoDlg.cpp

//inside OnInitDialog()
    // TODO: Add extra initialization here
    m_pTrayIcon.SetIcon( m_hIcon ); // application's icon
    m_pTrayIcon.SetTooltip( "Look at me!" );
    m_pTrayIcon.Show();
//...

All you need to do now, is set the icon's behavior, and you do that inside OnTrayNotify. For example, we want to display a menu when a user right clicks on our icon. I created mine like this:

If you press CTRL+W to open the class wizard, you will get a dialog box with two options: to create a new class for your menu, or to select an existing one. Choose "Select an existing class" and press OK. On the next dialog, you can see a list of classes available in your project. The most appropriate class would be your main dialog class, in this case CTrayDemoDlg. Select it and press OK. Now you can edit the code for your popup menu, and it will be inside CTrayDemoDlg class.

Now, let us edit our callback function:

// TrayDemoDlg.cpp

void CTrayDemoDlg::OnTrayNotify(WPARAM wParam, LPARAM lParam)
{   // switch lParam, which contains the event that occured
    // wParam would hold the icon's ID, but since we have
    // only one icon, we don't need to check that
    switch ( lParam )
    {
    case WM_LBUTTONDOWN:
        {   // left click, activate window
            // we would do here the same thing as if
            // the user clicked the "show dialog" menu
            // so don't duplicate the code
            OnShowdialog();
        }
        break;
    case WM_RBUTTONUP:
        {    // right click, show popup menu
            CMenu temp;
            CMenu *popup;
            CPoint loc;
            GetCursorPos( &loc );
            temp.LoadMenu( IDR_MNUPOPUP );
            popup = temp.GetSubMenu( 0 );
            popup->TrackPopupMenu( TPM_LEFTALIGN, loc.x, loc.y, this );
        }
        break;
    default:
        // do nothing
        break;
    }
}

We also might want to hide the taskbar button of your dialog, and we can do it inside OnInitDialog(). The demo app demonstrates how to accomplish that, and how to implement a simple "animation" - a flashing tray icon.

THE END - I hope someone will find this article useful in some way! (-:

Copyright

As for the copyright, all of this is copyrighted by me (T1TAN) and my pseudo-company SprdSoft Inc. That means that you can use this code in any app (private or commercial) without any restrictions whatsoever, since our company supports open source and free software. However, if you are going to use (parts of) the code, I'd like to hear from you, just to keep track of things.

If you have any comments, ideas or anything else about the article/code, feel free to contact me, I'd be glad to hear from you.

Greets & good programming!

History

• 25/01/2004 - First release.