X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..5267aefd85739afd26bd19bfba998005119db446:/interface/wx/taskbar.h?ds=sidebyside diff --git a/interface/wx/taskbar.h b/interface/wx/taskbar.h index 9eb2faaefb..c0acf5cebc 100644 --- a/interface/wx/taskbar.h +++ b/interface/wx/taskbar.h @@ -8,13 +8,50 @@ /** @class wxTaskBarIcon - @wxheader{taskbar.h} - 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 + "System Tray Protocol" (see http://freedesktop.org/wiki/Specifications/systemtray-spec) + 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 { @@ -27,23 +64,25 @@ public: /** Destroys the wxTaskBarIcon object, removing the icon if not already removed. */ - ~wxTaskBarIcon(); + virtual ~wxTaskBarIcon(); /** 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(); @@ -51,27 +90,56 @@ public: /** Returns @true if SetIcon() was called with no subsequent RemoveIcon(). */ - bool IsIconInstalled(); + bool IsIconInstalled() const; /** Returns @true if the object initialized successfully. */ - bool IsOk(); + 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. */ - bool PopupMenu(wxMenu* menu); + virtual bool PopupMenu(wxMenu* menu); /** Removes the icon previously set with SetIcon(). */ - bool RemoveIcon(); + virtual bool RemoveIcon(); /** Sets the icon, and optional tooltip text. */ - bool SetIcon(const wxIcon& icon, const wxString& tooltip); + virtual bool SetIcon(const wxIcon& icon, + const wxString& tooltip = wxEmptyString); + + /** + Returns true if system tray is available in the desktop environment the + app runs under. + + On Windows and Mac OS X, the tray is always available and this function + simply returns true. + + On Unix, X11 environment may or may not provide the tray, depending on + user's desktop environment. Most modern desktops support the tray via + the System Tray Protocol by freedesktop.org + (http://freedesktop.org/wiki/Specifications/systemtray-spec). + + @note Tray availability may change during application's lifetime + under X11 and so applications shouldn't cache the result. + + @note wxTaskBarIcon supports older GNOME 1.2 and KDE 1/2 methods of + adding icons to tray, but they are unreliable and this method + doesn't detect them. + + @since 2.9.0 + */ + static bool IsAvailable(); };