added wxTaskBarIcon::CreatePopupMenu API

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@27639 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -99,6 +99,12 @@ OTHER CHANGES
 2.5.3
 -----
 
+All (GUI):
+
+- added wxTaskBarIcon::CreatePopupMenu which is now recommended way
+  of showing popup menu; calling wxTaskBarIcon::PopupMenu directly
+  is discouraged
+
 Unix:
 
 - wxTaskBarIcon now supports freedesktop.org System Tray protocol
@@ -107,7 +113,7 @@ Unix:
 wxGTK:
 
 - fixed wrong colour of tooltips under some themes
-
+- implemented wxColourDialog as native dialog
 
 
 2.5.2

docs/latex/wx/taskbar.tex

@@ -33,7 +33,10 @@ be on by default.
 \wxheading{Event handling}
 
 To process input from a taskbar icon, use the following event handler macros to direct input to member
-functions that take a wxTaskBarIconEvent argument.
+functions that take a wxTaskBarIconEvent argument. Note that not all ports are
+required to send these events and so it's better to override
+\helpref{CreatePopupMenu}{wxtaskbariconcreatepopupmenu} if all that
+the application does is that it shows a popup menu in reaction to mouse click.
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
@@ -67,6 +70,19 @@ Default constructor.
 
 Destroys the wxTaskBarIcon object, removing the icon if not already removed.
 
+\membersection{wxTaskBarIcon::CreatePopupMenu}\label{wxtaskbariconcreatepopupmenu}
+
+\func{virtual wxMenu*}{CreatePopupMenu}{\void}
+
+This method is called by the library when the user requests popup menu
+(on Windows and Unix platforms, this is when the user right-clicks the icon).
+Override this function in order to provide popup menu associated with the icon.
+
+If CreatePopupIcon returns NULL (this happens by default),
+no menu is shown, otherwise the menu is
+displayed and then deleted by the library as soon as the user dismisses it.
+The events can be handled by a class derived from wxTaskBarIcon.
+
 \membersection{wxTaskBarIcon::IsIconInstalled}\label{wxtaskbariconisiconinstalled}
 
 \func{bool}{IsIconInstalled}{\void}
@@ -86,6 +102,13 @@ Returns true if the object initialized successfully.
 Pops up a menu at the current mouse position. The events can be handled by
 a class derived from wxTaskBarIcon.
 
+\wxheading{Note}
+
+It is recommended to override
+\helpref{CreatePopupIcon}{wxtaskbariconcreatepopupmenu}
+callback instead of calling this method from event handler, because some
+ports (e.g. wxCocoa) may not implement PopupMenu and mouse click events at all.
+
 \membersection{wxTaskBarIcon::RemoveIcon}\label{wxtaskbariconremoveicon}
 
 \func{bool}{RemoveIcon}{\void}

include/wx/taskbar.h

@@ -7,6 +7,8 @@
 
 #include "wx/event.h"
 
+class WXDLLIMPEXP_ADV wxTaskBarIconEvent;
+
 // ----------------------------------------------------------------------------
 // wxTaskBarIconBase: define wxTaskBarIcon interface
 // ----------------------------------------------------------------------------
@@ -15,8 +17,22 @@ class WXDLLIMPEXP_ADV wxTaskBarIconBase : public wxEvtHandler
 {
 public:
     wxTaskBarIconBase() { }
+    
+    // Operations:
+    virtual bool SetIcon(const wxIcon& icon,
+                         const wxString& tooltip = wxEmptyString) = 0;
+    virtual bool RemoveIcon() = 0;
+    virtual bool PopupMenu(wxMenu *menu) = 0;
 
+protected:
+    // creates menu to be displayed when user clicks on the icon
+    virtual wxMenu *CreatePopupMenu() { return NULL; }
+    
 private:
+    // default events handling, calls CreatePopupMenu:
+    void OnRightButtonDown(wxEvent& event);
+    
+    DECLARE_EVENT_TABLE()
     DECLARE_NO_COPY_CLASS(wxTaskBarIconBase)
 };
 

samples/taskbar/tbtest.cpp

@@ -110,7 +110,6 @@ 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_RIGHT_DOWN   (MyTaskBarIcon::OnRButtonDown)
     EVT_TASKBAR_LEFT_DCLICK  (MyTaskBarIcon::OnLButtonDClick)
 END_EVENT_TABLE()
 
@@ -138,15 +137,15 @@ void MyTaskBarIcon::OnMenuSetNewIcon(wxCommandEvent&)
 }
 
 // Overridables
-void MyTaskBarIcon::OnRButtonDown(wxEvent&)
+wxMenu *MyTaskBarIcon::CreatePopupMenu()
 {
-    wxMenu      menu;
+    wxMenu *menu = new wxMenu;
+    
+    menu->Append(PU_RESTORE, _T("&Restore TBTest"));
+    menu->Append(PU_NEW_ICON,_T("&Set New Icon"));
+    menu->Append(PU_EXIT,    _T("E&xit"));
 
-    menu.Append(PU_RESTORE, _T("&Restore TBTest"));
-    menu.Append(PU_NEW_ICON,_T("&Set New Icon"));
-    menu.Append(PU_EXIT,    _T("E&xit"));
-
-    PopupMenu(&menu);
+    return menu;
 }
 
 void MyTaskBarIcon::OnLButtonDClick(wxEvent&)

samples/taskbar/tbtest.h

@@ -14,12 +14,13 @@ class MyTaskBarIcon: public wxTaskBarIcon
 public:
     MyTaskBarIcon() {};
 
-    void OnRButtonDown(wxEvent&);
     void OnLButtonDClick(wxEvent&);
     void OnMenuRestore(wxCommandEvent&);
     void OnMenuExit(wxCommandEvent&);
     void OnMenuSetNewIcon(wxCommandEvent&);
 
+    virtual wxMenu *CreatePopupMenu();
+
 DECLARE_EVENT_TABLE()
 };
 

src/common/taskbarcmn.cpp

@@ -35,4 +35,19 @@ DEFINE_EVENT_TYPE( wxEVT_TASKBAR_RIGHT_UP )
 DEFINE_EVENT_TYPE( wxEVT_TASKBAR_LEFT_DCLICK )
 DEFINE_EVENT_TYPE( wxEVT_TASKBAR_RIGHT_DCLICK )
 
-#endif //def wxHAS_TASK_BAR_ICON
+
+BEGIN_EVENT_TABLE(wxTaskBarIconBase, wxEvtHandler)
+    EVT_TASKBAR_RIGHT_DOWN(wxTaskBarIconBase::OnRightButtonDown)
+END_EVENT_TABLE()
+
+void wxTaskBarIconBase::OnRightButtonDown(wxEvent& WXUNUSED(event))
+{
+    wxMenu *menu = CreatePopupMenu();
+    if (menu)
+    {
+        PopupMenu(menu);
+        delete menu;
+    }
+}
+    
+#endif // defined(wxHAS_TASK_BAR_ICON)