interface revisions of ta*h te*h headers; grouped wxTextAttr #defines into enums to make it easier to document them

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

interface/wx/taskbar.h

@@ -9,11 +9,49 @@
 /**
     @class wxTaskBarIcon
 
-    This class represents a taskbar icon. A taskbar icon is an icon that appears in
-    the 'system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information.
+    This class represents a taskbar icon.
+    A taskbar icon is an icon that appears in the 'system tray' and responds to
+    mouse clicks, optionally with a tooltip above it to help provide information.
+
+    @section taskbaricon_xnote X Window System Note
+    Under X Window System, the window manager must support either the
+    @link http://freedesktop.org/wiki/Specifications/systemtray-spec "System Tray Protocol"
+    by freedesktop.org (WMs used by modern desktop environments such as GNOME >= 2,
+    KDE >= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and KDE 1 and 2.
+
+    If it doesn't, the icon will appear as a toplevel window on user's desktop.
+    Because not all window managers have system tray, there's no guarantee that
+    wxTaskBarIcon will work correctly under X Window System and so the applications
+    should use it only as an optional component of their user interface.
+    The user should be required to explicitly enable the taskbar icon on Unix,
+    it shouldn't be on by default.
+
+    @beginEventTable{wxTaskBarIconEvent}
+    Note that not all ports are required to send these events and so it's better
+    to override wxTaskBarIcon::CreatePopupMenu() if all that the application does
+    is that it shows a popup menu in reaction to mouse click.
+    @event{EVT_TASKBAR_MOVE(func)}
+        Process a wxEVT_TASKBAR_MOVE event.
+    @event{EVT_TASKBAR_LEFT_DOWN(func)}
+        Process a wxEVT_TASKBAR_LEFT_DOWN event.
+    @event{EVT_TASKBAR_LEFT_UP(func)}
+        Process a wxEVT_TASKBAR_LEFT_UP event.
+    @event{EVT_TASKBAR_RIGHT_DOWN(func)}
+        Process a wxEVT_TASKBAR_RIGHT_DOWN event.
+    @event{EVT_TASKBAR_RIGHT_UP(func)}
+        Process a wxEVT_TASKBAR_RIGHT_UP event.
+    @event{EVT_TASKBAR_LEFT_DCLICK(func)}
+        Process a wxEVT_TASKBAR_LEFT_DCLICK event.
+    @event{EVT_TASKBAR_RIGHT_DCLICK(func)}
+        Process a wxEVT_TASKBAR_RIGHT_DCLICK event.
+    @event{EVT_TASKBAR_CLICK(func)}
+        This is a synonym for either EVT_TASKBAR_RIGHT_DOWN or UP depending on
+        the platform, use this event macro to catch the event which should result
+        in the menu being displayed on the current platform.
+    @endEventTable
 
     @library{wxadv}
-    @category{FIXME}
+    @category{misc}
 */
 class wxTaskBarIcon : public wxEvtHandler
 {
@@ -31,18 +69,20 @@ public:
     /**
         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 CreatePopupMenu 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.
+        If CreatePopupMenu() 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.
     */
     virtual wxMenu* CreatePopupMenu();
 
     /**
-        This method is similar to wxWindow::Destroy and can
-        be used to schedule the task bar icon object for the delayed destruction: it
-        will be deleted during the next event loop iteration, which allows the task bar
+        This method is similar to wxWindow::Destroy and can be used to schedule
+        the task bar icon object for the delayed destruction: it will be deleted
+        during the next event loop iteration, which allows the task bar
         icon to process any pending events for it before being destroyed.
     */
     void Destroy();
@@ -58,8 +98,13 @@ public:
     bool IsOk() const;
 
     /**
-        Pops up a menu at the current mouse position. The events can be handled by
-        a class derived from wxTaskBarIcon.
+        Pops up a menu at the current mouse position.
+        The events can be handled by a class derived from wxTaskBarIcon.
+
+        @note
+        It is recommended to override CreatePopupMenu() 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.
     */
     virtual bool PopupMenu(wxMenu* menu);