Documentation of CTrayIcon
===========================

--------------------------------------------------------------------
|| Programmer: Fritz Philipp alias WebFritzi (www.webfritzi.de.vu)||
--------------------------------------------------------------------


1. Public Methods
2. The message WM_TRAYMESSAGE
3. An example-windowproc



1. Public Methods
------------------

In CTrayIcon, we have the following public methods:

    CTrayIcon(HINSTANCE hInstance, HWND hWnd, HICON hIcon, LPTSTR lpszTip)
    CTrayIcon(HINSTANCE hInstance, HWND hWnd, WORD wIconID, LPTSTR lpszTip)
    CTrayIcon(HINSTANCE hInstance, WNDPROC WndProc, HICON hIcon, LPTSTR lpszTip)
    CTrayIcon(HINSTANCE hInstance, WNDPROC WndProc, WORD wIconID, LPTSTR lpszTip)
    ~CTrayIcon();

    VOID    Show()
    VOID    Hide()
    BOOL    IsVisible()
    VOID    DoPopup()
    VOID    SetToolTip(LPTSTR lpszTip)
    UINT    GetToolTip(LPTSTR lpszBuf, UINT uiBufSize)
    VOID    SetIcon(HICON hIcon)
    HICON   GetIcon()
    VOID    SetPopupMenu(HMENU hMenu)
    HMENU   GetPopupMenu()
    BOOL    SetPopupReaction(WORD wPR)
    WORD    GetPopupReaction()
    VOID    WaitForDoubleClick(BOOL bWait)
    BOOL    GetWaitForDoubleClick()
    HWND    GetMainWindow()
    VOID    ShowBalloon(LPTSTR szTitle, LPTSTR szInfo, UINT uiTimeout, DWORD dwIcon)


CTrayIcon(HINSTANCE hInstance, HWND hWnd, HICON hIcon, LPTSTR lpszTip)
CTrayIcon(HINSTANCE hInstance, HWND hWnd, WORD wIconID, LPTSTR lpszTip)
------------------------------------------------------------------------
Constructors. I think, the first parameter should be clear. In the second
you specify the window which will receive the Message WM_TRAYMESSAGE (see 2)
from the tray icon object. In addition, if a popupmenu is specified (using
CTrayIcon::SetPopupMenu), this window will receive all the messages coming
from this popup menu. The third parameter is a HICON handle to the icon, you'd
like to see in the tray. The last parameter is a pointer to a string that 
consists of the tooltip text. This text is shown in a small window when you
place the mouse cursor over the icon in the tray.
The second constructor works as the first except in the third parameter. Here,
you can specify a resource ID for your icon.


CTrayIcon(HINSTANCE hInstance, WNDPROC WndProc, HICON hIcon, LPTSTR lpszTip)
CTrayIcon(HINSTANCE hInstance, WNDPROC WndProc, WORD wIconID, LPTSTR lpszTip)
------------------------------------------------------------------------
Other contructors. As you can see, everything is equal to the first two constructors,
except the second parameter. In this parameter you can specify a callback function
of type WNDPROC, i.e. LRESULT CALLBACK (HWND, UINT, WPARAM, LPARAM). If you create your
trayicon with this constructor, all the messages (WM_TRAYMESSAGE for mouse actions and
WM_COMMAND for menu clicks) are sent to the specified callback function.


VOID    Show()
VOID    Hide()
BOOL    IsVisible()
--------------------
With the first and second method you can show or hide the icon in the tray.
With CTrayIcon::IsVisible() you can determine, whether the icon is shown in the
tray or not.


VOID    DoPopup()
------------------
This method pops up the popup menu (if present) at the current position of the
mouse cursor.


VOID    SetToolTip(LPTSTR lpszTip)
-----------------------------------
With this method you can set the tool tip text.


UINT    GetToolTip(LPTSTR lpszBuf, UINT uiBufSize)
---------------------------------------------------
With this method you can let CTrayIcon write the tool tip text into a buffer.
With uiBufSize you specify the maximum amount of bytes in the buffer the text
should be copied into (lpszBuf). The return value is the number of characters
in the tool tip text, including the terminating NULL character. Setting lpszBuf
to NULL, the function doesn't do anything but returning this value. By this, you
can determine which value uiBufSize should be set to.


VOID    SetIcon(HICON hIcon)
HICON   GetIcon()
-----------------------------
I think, I don't have to explain these methods.


VOID    SetPopupMenu(HMENU hMenu, INT index)
VOID    SetPopupMenu(WORD wMenuID, INT index)
HMENU   GetPopupMenu()
----------------------------------
A CTrayIcon object need not have a popup menu! But if you want one to popup after
a certain mouse action, these methods are very useful. I think, the third one is
clear. If you have created a menu in your resources, you can just specify
the Menu ID in the first parameter. The index is the zero-based number of the 
popup menu in the menu. If you have created your menu by code, you should call
the first function.


BOOL    SetPopupReaction(WORD wPR)
WORD    GetPopupReaction()
-----------------------------------
With CTrayIcon::SetPopupReaction() you can specify when the popup menu should pop
up. wPR can have the following values:

PR_LBUTTON:   The popup menu pops up when you click the left mouse button.
PR_RBUTTON:   The popup menu pops up when you click the right mouse button.
PR_BOTH   :   The popup menu pops up when you click the right or the left mouse button.
PR_NONE   :   The popup menu never pops up (default when no menu is specified)

The return value is TRUE, when wPR is set to one of these values. Otherwise it's FALSE.


VOID    WaitForDoubleClick(BOOL bWait)
BOOL    GetWaitForDoubleClick()
---------------------------------------
If, after a leftclick on the icon, you want your trayicon to wait for half a second in 
order to check if the user performs a doubleclick, you can call
CTrayIcon::WaitForDoubleClick(TRUE). This can be useful when you would like to perform
two different actions for a simple leftclick and a doubleclick. The default is FALSE.


HWND    GetMainWindow()
------------------------
This function returns the window which receives popup menu messages and WM_TRAYMESSAGE
messages (if any). It's the same window as in the second parameter of the first two
constructors or NULL, if you have used another constructor.


WNDPROC GetWindowProc()
------------------------
GetWindowProc() returns the callback function (if any) that receives the trayicon 
messages. It's the same value as in the second parameter of the second two
constructors or NULL, if you have used another constructor.


VOID    ShowBalloon(LPTSTR szTitle, LPTSTR szInfo, UINT uiTimeout, DWORD dwIcon)
---------------------------------------------------------------------------------
With this function you can show a balloon (bubble) with some descripting text in it
right above your tray icon. The text which you specify in szTitle will be the header
of the text in the bubble and displayed in bold letters. Below, the text in szInfo
follows. The parameter uiTimeout is a time value (in milliseconds) specifying the
maximal display durance of the bubble. In dwIcon you specify a value which stands
for the icon that is displayed in the bubble. You have the following possibilities:
NIIF_NONE      : No icon
NIIF_INFO      : A bubble with a question mark
NIIF_WARNING   : A warning yellow triangle with a "!" in it
NIIF_ERROR     : A red error icon
NIIF_GUID      : no idea what this is, sorry
NIIF_QUESTION  : same as NIIF_INFO
NIIF_ICON_MASK : no idea what this is (it is reserved for future use, I think)
NIIF_NOSOUND   : no sound is played (ONLY Shell Version 6)
NIIF_USER      : ONLY SP2 - use the tray icon itself




2. The message WM_TRAYMESSAGE
------------------------------
The main window or the window procedure, which you specify in the second parameter of 
the constructors, receives this message when the mouse cursor is moved over the tray 
icon or when a mouse button is clicked while the cursor is over the icon. The message looks like this:

wParam: A pointer to the CTrayIcon object which sent the message;
lParam: One of the values WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN,
        WM_RBUTTONUP, WM_LBUTTONDBLCLK.

If you'd like to get the current mouse coordinates, you can call GetCursorPos().





3. An example-windowproc
-------------------------
LRESULT CALLBACK AppWndProc(HWND hwnd, UINT uiMsg, WPARAM wParam, LPARAM lParam)
{
   static CTrayIcon* TrayIcon;

   switch(uiMsg)
   {
      case WM_CREATE:
         // Create the tray icon
         TrayIcon = new CTrayIcon(((LPCREATESTRUCT)lParam)->hInstance,
                                  hwnd,
                                  ID_ICO_MYICON,
                                  TEXT("My Tool Tip Text")
                                 );
         // Set a new popup menu
         TrayIcon->SetPopupMenu(ID_MENU, 0);
         return 0;


      case WM_COMMAND:
         switch(LOWORD(wParam))  // Switch between control IDs
         {
            // The menu item "ShoW" was clicked
            case ID_MI_SHOW:
               SendMessage(hwnd, WM_SYSCOMMAND, SC_RESTORE, 0);
               break;

            // The menu item "Exit" was clicked
            case ID_MI_EXIT:
               SendMessage(hwnd, WM_CLOSE, 0, 0);
               break;
         }
         return 0;


      case WM_SYSCOMMAND:
         if(wParam == SC_MINIMIZE)     // The main window shall be minimized
         {
            TrayIcon->Show();          // Show the tray icon
            ShowWindow(hwnd, SW_HIDE); // Hide the main window
            return 0;
         }
         if(wParam == SC_RESTORE)      // The main window shall be restored
         {
            TrayIcon->Hide();          // Hide the tray icon
            SetForegroundWindow(hwnd); // Show main window and put it on the top of the Z order
         }
         break;


      // A mouse action was performed over the tray icon
      case WM_TRAYMESSAGE:
         if(lParam == WM_LBUTTONUP)    // The tray icon was leftclicked
            SendMessage(hwnd, WM_SYSCOMMAND, SC_RESTORE, 0);
         return 0;


      case WM_DESTROY:
         delete TrayIcon;
         PostQuitMessage(0);
         return 0;
   }

   return DefWindowProc(hwnd, uiMsg, wParam, lParam);
}