Tray Icon Class

Objective Toolkit User's Guide
Rogue Wave web site: Home Page | Main Documentation Page

15.9 Tray Icon Class

The SECTrayIcon class helps you create applications that are invoked via the Windows tray interface. Animated icons are supported. A System Tray Icon is a user interface metaphor that was introduced by Windows 95. If you look at the rightmost edge of the Windows 95 taskbar, there is a small "tray" of application icons and a system clock.

SECTrayIcon provides your application with an easy-to-use mechanism for adding your own custom icons to the system tray and providing user interface feedback such as tooltip text, context menu support, and animated icons.

Figure 127: Objective Toolkit Tray Icon Class Hierarchy

15.9.1 To incorporate the Tray Icon Class into your application

In your main window class (main frame or dialog), add an SECTrayIcon data member for each tray icon you want to display. For example:
In the initialization code for your main window class, create the tray icon by calling the Create() method.
In the resource editor, add an icon resource and then set the icon with the SetIcon() method.

Optionally, set tooltip text with the SetTip() method.

m_TrayApp.SetTip(_T("Stingray Tray Icon Demo"));

Display the tray icon with the Show() method.
The SECTrayIcon destructor automatically cleans up the icon; however, you can still issue a Destroy() call directly.

15.9.2 To add notification handlers for mouse events

The following steps set up a notification handler to display a context menu in response to a right-click.

Complete the steps in Section 15.9.1.
For each tray icon, create a unique notification ID or use the GetNextNotifyID() method to generate one on the fly.
Add the notification ID as the second parameter to the Create() method call.

Add the WM_SEC_TRAYICON_NOTIFY message using the ON_MESSAGE macro in the message map. The tray icon sends notifications via this user message. You can also specify your own message ID as an optional parameter to the SECTrayIcon::Create() method call.

    
ON_MESSAGE(WM_SEC_TRAYICON_NOTIFY,
               OnTrayIconNotify)

Add a message handler for this message. The wParam contains the notification ID passed to the Create() method. The lParam contains the mouse message. For example:

LRESULT CTrayIconDlg::OnTrayIconNotify(WPARAM wParam, LPARAM lParam)
{
    // Use the wParam to identify which tray icon 
    if(wParam==m_TrayNotifyId) {

        // lParam identifies the mouse message
        switch(lParam) {
            case WM_MOUSEMOVE:
           // mousemove is a good place to 
           // change tooltip text – for example 
           // if you were displaying time of day

            case WM_RBUTTONUP:
            // the SECTrayIcon::ShowContextMenu
            // static member makes it a snap to
            // display popup menus—-all the 
            // positioning and message routing 
            // is done automatically for you.
            SECTrayIcon::ShowContextMenu(this,
                         IDR_MENU_NOTIFY);
            break; 

            case WM_LBUTTONDBLCLK:
            AfxMessageBox(
                _T("You just double clicked me!"));
            break;
         }
    }
    return 0L;
}

15.9.3 To animate a tray icon

Complete the steps in Section 15.9.1.
In the resource editor, add icons for each frame of the animation.

After the SECTrayIcon::Create() method call, call the AddState() method and specify a unique ID for each state, the icon to display, the tooltip to display, and a frame delay time. The default time delay is 255 milliseconds. If you need to specify a different time delay, multiply the delay parameter by 17 to determine the time in milliseconds.

m_tray.AddState(IDI_SCROLL_ON0, IDI_SCROLL_ON0,
                strOn, nFrameDelay);
m_tray.AddState(IDI_SCROLL_ON1, IDI_SCROLL_ON1,
                strOn, nFrameDelay);
m_tray.AddState(IDI_SCROLL_ON2, IDI_SCROLL_ON2,
                strOn, nFrameDelay);
m_tray.AddState(IDI_SCROLL_ON3, IDI_SCROLL_ON3,
                strOn, nFrameDelay);
m_tray.AddState(IDI_SCROLL_ON4, IDI_SCROLL_ON4,
                strOn, nFrameDelay);
m_tray.AddState(IDI_SCROLL_ON5, IDI_SCROLL_ON5,
                strOn, nFrameDelay);

After the call to the Show() method, call the Play() method to start the animation and the Stop() to halt the animation.

15.9.4 Tray Icon Sample

Refer to the trayicon sample (\Samples\Toolkit\MFC\UIExt\TrayIcon) for more information. Animations are also demonstrated in this sample. This sample does not ship with the product. For information on how to obtain this sample, see Section 3.6.1, "Location of Sample Code," in the Stingray Studio Getting Started Guide.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.