wxTaskBarIcon

This class installs an icon on the system tray (Windows, Gnome, or KDE) or dock (Mac OS X). Clicking on the icon will pop up a menu that the application supplies, and an optional tooltip can be shown when the mouse hovers over the icon. This technique gives quick access to important application functionality without having to use the regular application user interface. The application can display status information by switching icons, as per the battery and connection indicators in Windows.

Figure 12-8 shows the result of running the wxTaskBarIcon sample on Windows (see samples/taskbar). The wxWidgets icon is installed, and hovering the mouse pointer over the icon shows the tooltip text "wxTaskBarIconSample." Right-clicking on the icon shows the menu with three options. Selecting Set New Icon sets the icon to a smiley face and also resets the tooltip text to a new string.

Figure 12-8. wxTaskBarIcon on Windows

The implementation of a wxTaskBarIcon-derived class can be very simple, as Listing 12-4 shows (taken from the wxTaskBarIcon sample). The derived class MyTaskBarIcon overrides CreatePopupMenu and implements event handlers to intercept a left double-click and three menu commands.

Listing 12-4. Deriving from wxTaskBarIcon

 class MyTaskBarIcon: public wxTaskBarIcon { public:     MyTaskBarIcon() {};     void OnLeftButtonDClick(wxTaskBarIconEvent&);     void OnMenuRestore(wxCommandEvent&);     void OnMenuExit(wxCommandEvent&);     void OnMenuSetNewIcon(wxCommandEvent&);     virtual wxMenu *CreatePopupMenu(); DECLARE_EVENT_TABLE() }; enum {     PU_RESTORE = 10001,     PU_NEW_ICON,     PU_EXIT, }; BEGIN_EVENT_TABLE(MyTaskBarIcon, wxTaskBarIcon)     EVT_MENU(PU_RESTORE, MyTaskBarIcon::OnMenuRestore)     EVT_MENU(PU_EXIT,    MyTaskBarIcon::OnMenuExit)     EVT_MENU(PU_NEW_ICON,MyTaskBarIcon::OnMenuSetNewIcon)     EVT_TASKBAR_LEFT_DCLICK  (MyTaskBarIcon::OnLeftButtonDClick) END_EVENT_TABLE() void MyTaskBarIcon::OnMenuRestore(wxCommandEvent& ) {     dialog->Show(true); } void MyTaskBarIcon::OnMenuExit(wxCommandEvent& ) {     dialog->Close(true); } void MyTaskBarIcon::OnMenuSetNewIcon(wxCommandEvent&) {     wxIcon icon(smile_xpm);     if (!SetIcon(icon, wxT("wxTaskBarIcon Sample - a different icon")))         wxMessageBox(wxT("Could not set new icon.")); } // Overridables wxMenu *MyTaskBarIcon::CreatePopupMenu() {     wxMenu *menu = new wxMenu;     menu->Append(PU_RESTORE, wxT("&Restore TBTest"));     menu->Append(PU_NEW_ICON,wxT("&Set New Icon"));     menu->Append(PU_EXIT,    wxT("E&xit"));     return menu; } void MyTaskBarIcon::OnLeftButtonDClick(wxTaskBarIconEvent&) {     dialog->Show(true); } 

The rest of the code to show a dialog and install the initial icon is equally straightforward, as Listing 12-5 shows.

Listing 12-5. Showing a Taskbar Icon

[View full width]

 #include "wx/wx.h" #include "wx/taskbar.h" // Define a new application class MyApp: public wxApp { public:     bool OnInit(void); }; class MyDialog: public wxDialog { public:     MyDialog(wxWindow* parent, const wxWindowID id, const wxString& title,         const wxPoint& pos, const wxSize& size, const long windowStyle =  wxDEFAULT_DIALOG_STYLE);     ~MyDialog();     void OnOK(wxCommandEvent& event);     void OnExit(wxCommandEvent& event);     void OnCloseWindow(wxCloseEvent& event);     void Init(void); protected:     MyTaskBarIcon   *m_taskBarIcon; DECLARE_EVENT_TABLE() }; #include "../sample.xpm" #include "smile.xpm" MyDialog   *dialog = NULL; IMPLEMENT_APP(MyApp) bool MyApp::OnInit(void) {     // Create the main frame window     dialog = new MyDialog(NULL, wxID_ANY, wxT("wxTaskBarIcon Test Dialog"),  wxDefaultPosition, wxSize(365, 290));     dialog->Show(true);     return true; } BEGIN_EVENT_TABLE(MyDialog, wxDialog)     EVT_BUTTON(wxID_OK, MyDialog::OnOK)     EVT_BUTTON(wxID_EXIT, MyDialog::OnExit)     EVT_CLOSE(MyDialog::OnCloseWindow) END_EVENT_TABLE() MyDialog::MyDialog(wxWindow* parent, const wxWindowID id, const wxString& title,     const wxPoint& pos, const wxSize& size, const long windowStyle):   wxDialog(parent, id, title, pos, size, windowStyle) {     Init(); } MyDialog::~MyDialog() {     delete m_taskBarIcon; } void MyDialog::OnOK(wxCommandEvent& WXUNUSED(event)) {     Show(false); } void MyDialog::OnExit(wxCommandEvent& WXUNUSED(event)) {     Close(true); } void MyDialog::OnCloseWindow(wxCloseEvent& WXUNUSED(event)) {     Destroy(); } void MyDialog::Init(void) {   (void)new wxStaticText(this, wxID_ANY, wxT("Press 'Hide me' to hide me, Exit to quit."),                          wxPoint(10, 20));   (void)new wxStaticText(this, wxID_ANY, wxT("Double-click on the taskbar icon to show me  again."),                          wxPoint(10, 40));   (void)new wxButton(this, wxID_EXIT, wxT("Exit"), wxPoint(185, 230), wxSize(80, 25));   (new wxButton(this, wxID_OK, wxT("Hide me"), wxPoint(100, 230), wxSize(80,  25)))->SetDefault();   Centre(wxBOTH);   m_taskBarIcon = new MyTaskBarIcon();   if (!m_taskBarIcon->SetIcon(wxIcon(sample_xpm), wxT("wxTaskBarIcon Sample")))         wxMessageBox(wxT("Could not set icon.")); } 

wxTaskBarIcon Events

To process events from a taskbar icon, use the event handler macros listed in Table 12-11 to direct input to member functions that take a wxTaskBarIcon Event argument. Note that not all ports are required to send these events, and so you should override CreatePopupMenu if you want to show a popup menu in reaction to a mouse click. Note also that wxTaskBarIconEvent doesn't pass any mouse status information such as position.

Table 12-11. wxTaskBarIcon Events

EVT_TASKBAR_MOVE(func)	The mouse moved over the icon.
EVT_TASKBAR_LEFT_DOWN(func)	The left mouse button was pressed down.
EVT_TASKBAR_LEFT_UP(func)	The left mouse button was released.
EVT_TASKBAR_RIGHT_DOWN(func)	The right mouse button was pressed down.
EVT_TASKBAR_RIGHT_UP(func)	The right mouse button was released.
EVT_TASKBAR_LEFT_DCLICK(func)	The left mouse button was double-clicked.
EVT_TASKBAR_RIGHT_DCLICK(func)	The right mouse button was double-clicked.

wxTaskBarIcon Member Functions

The wxTaskBarIcon API is very simple. These are all the member functions for this class.

CreatePopupMenu is a virtual function that should be overridden by the derived class to return a new wxMenu when called by wxWidgets in response to a wxEVT_TASKBAR_RIGHT_DOWN event (this event is simulated on Mac OS X). wxWidgets will also delete the menu when it is dismissed.

IsIconInstalled returns true if SetIcon was successfully called.

IsOk returns true if the wxTaskBarIcon object initialized successfully.

PopupMenu shows a menu at the current position. It's not recommended to call this directly; instead, override CreatePopupMenu and let wxWidgets show the menu for you.

RemoveIcon removes the icon previously set with SetIcon.

SetIcon sets an icon (wxIcon) and optional tooltip text. You can call this multiple times.