interface/wx/taskbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        taskbar.h
   3 // Purpose:     interface of wxTaskBarIcon
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10    On OSX Cocoa the taskbar icon can be in the doc or in the status area.
  11    This enumeration can be used to select which will be instantiated.
  12 */
  13 enum wxTaskBarIconType
  14 {
  15     wxTBI_DOCK,
  16     wxTBI_CUSTOM_STATUSITEM,
  17     wxTBI_DEFAULT_TYPE
  18 };
  19
  20
  21
  22 /**
  23     @class wxTaskBarIconEvent
  24
  25     The event class used by wxTaskBarIcon.
  26     For a list of the event macros meant to be used with wxTaskBarIconEvent,
  27     please look at wxTaskBarIcon description.
  28
  29     @library{wxadv}
  30     @category{events}
  31 */
  32 class wxTaskBarIconEvent : public wxEvent
  33 {
  34 public:
  35     /**
  36         Constructor.
  37     */
  38     wxTaskBarIconEvent(wxEventType evtType, wxTaskBarIcon *tbIcon);
  39 };
  40
  41
  42 /**
  43     @class wxTaskBarIcon
  44
  45     This class represents a taskbar icon.
  46     A taskbar icon is an icon that appears in the 'system tray' and responds to
  47     mouse clicks, optionally with a tooltip above it to help provide information.
  48
  49
  50     @section taskbaricon_xnote X Window System Note
  51
  52     Under X Window System, the window manager must support either the
  53     "System Tray Protocol" (see http://freedesktop.org/wiki/Specifications/systemtray-spec)
  54     by freedesktop.org (WMs used by modern desktop environments such as GNOME >= 2,
  55     KDE >= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and KDE 1 and 2.
  56
  57     If it doesn't, the icon will appear as a toplevel window on user's desktop.
  58     Because not all window managers have system tray, there's no guarantee that
  59     wxTaskBarIcon will work correctly under X Window System and so the applications
  60     should use it only as an optional component of their user interface.
  61     The user should be required to explicitly enable the taskbar icon on Unix,
  62     it shouldn't be on by default.
  63
  64     @beginEventEmissionTable{wxTaskBarIconEvent}
  65     Note that not all ports are required to send these events and so it's better
  66     to override wxTaskBarIcon::CreatePopupMenu() if all that the application does
  67     is that it shows a popup menu in reaction to mouse click.
  68     @event{EVT_TASKBAR_MOVE(func)}
  69         Process a @c wxEVT_TASKBAR_MOVE event.
  70     @event{EVT_TASKBAR_LEFT_DOWN(func)}
  71         Process a @c wxEVT_TASKBAR_LEFT_DOWN event.
  72     @event{EVT_TASKBAR_LEFT_UP(func)}
  73         Process a @c wxEVT_TASKBAR_LEFT_UP event.
  74     @event{EVT_TASKBAR_RIGHT_DOWN(func)}
  75         Process a @c wxEVT_TASKBAR_RIGHT_DOWN event.
  76     @event{EVT_TASKBAR_RIGHT_UP(func)}
  77         Process a @c wxEVT_TASKBAR_RIGHT_UP event.
  78     @event{EVT_TASKBAR_LEFT_DCLICK(func)}
  79         Process a @c wxEVT_TASKBAR_LEFT_DCLICK event.
  80     @event{EVT_TASKBAR_RIGHT_DCLICK(func)}
  81         Process a @c wxEVT_TASKBAR_RIGHT_DCLICK event.
  82     @event{EVT_TASKBAR_CLICK(func)}
  83         This is a synonym for either EVT_TASKBAR_RIGHT_DOWN or UP depending on
  84         the platform, use this event macro to catch the event which should result
  85         in the menu being displayed on the current platform.
  86     @endEventTable
  87
  88     @library{wxadv}
  89     @category{misc}
  90 */
  91 class wxTaskBarIcon : public wxEvtHandler
  92 {
  93 public:
  94     /**
  95         Default constructor.  The iconType is only applicable on wxOSX_Cocoa.
  96     */
  97     wxTaskBarIcon(wxTaskBarIconType iconType = wxTBI_DEFAULT_TYPE);
  98
  99     /**
 100         Destroys the wxTaskBarIcon object, removing the icon if not already removed.
 101     */
 102     virtual ~wxTaskBarIcon();
 103
 104     /**
 105         This method is similar to wxWindow::Destroy and can be used to schedule
 106         the task bar icon object for the delayed destruction: it will be deleted
 107         during the next event loop iteration, which allows the task bar
 108         icon to process any pending events for it before being destroyed.
 109     */
 110     void Destroy();
 111
 112     /**
 113         Returns @true if SetIcon() was called with no subsequent RemoveIcon().
 114     */
 115     bool IsIconInstalled() const;
 116
 117     /**
 118         Returns @true if the object initialized successfully.
 119     */
 120     bool IsOk() const;
 121
 122     /**
 123         Pops up a menu at the current mouse position.
 124         The events can be handled by a class derived from wxTaskBarIcon.
 125
 126         @note
 127         It is recommended to override CreatePopupMenu() callback instead of
 128         calling this method from event handler, because some ports (e.g. wxCocoa)
 129         may not implement PopupMenu() and mouse click events at all.
 130     */
 131     virtual bool PopupMenu(wxMenu* menu);
 132
 133     /**
 134         Removes the icon previously set with SetIcon().
 135     */
 136     virtual bool RemoveIcon();
 137
 138     /**
 139         Sets the icon, and optional tooltip text.
 140     */
 141     virtual bool SetIcon(const wxIcon& icon,
 142                          const wxString& tooltip = wxEmptyString);
 143
 144     /**
 145         Returns true if system tray is available in the desktop environment the
 146         app runs under.
 147
 148         On Windows and Mac OS X, the tray is always available and this function
 149         simply returns true.
 150
 151         On Unix, X11 environment may or may not provide the tray, depending on
 152         user's desktop environment. Most modern desktops support the tray via
 153         the System Tray Protocol by freedesktop.org
 154         (http://freedesktop.org/wiki/Specifications/systemtray-spec).
 155
 156         @note Tray availability may change during application's lifetime
 157               under X11 and so applications shouldn't cache the result.
 158
 159         @note wxTaskBarIcon supports older GNOME 1.2 and KDE 1/2 methods of
 160               adding icons to tray, but they are unreliable and this method
 161               doesn't detect them.
 162
 163         @since 2.9.0
 164     */
 165     static bool IsAvailable();
 166
 167 protected:
 168
 169     /**
 170         This method is called by the library when the user requests popup menu
 171         (on Windows and Unix platforms, this is when the user right-clicks the icon).
 172
 173         Override this function in order to provide popup menu associated with the icon.
 174         If CreatePopupMenu() returns @NULL (this happens by default), no menu is shown,
 175         otherwise the menu is displayed and then deleted by the library as soon as the
 176         user dismisses it.
 177
 178         The events can be handled by a class derived from wxTaskBarIcon.
 179     */
 180     virtual wxMenu* CreatePopupMenu();
 181 };
 182
 183
 184 wxEventType wxEVT_TASKBAR_MOVE;
 185 wxEventType wxEVT_TASKBAR_LEFT_DOWN;
 186 wxEventType wxEVT_TASKBAR_LEFT_UP;
 187 wxEventType wxEVT_TASKBAR_RIGHT_DOWN;
 188 wxEventType wxEVT_TASKBAR_RIGHT_UP;
 189 wxEventType wxEVT_TASKBAR_LEFT_DCLICK;
 190 wxEventType wxEVT_TASKBAR_RIGHT_DCLICK;
 191 wxEventType wxEVT_TASKBAR_CLICK;
 192 wxEventType wxEVT_TASKBAR_BALLOON_TIMEOUT;
 193 wxEventType wxEVT_TASKBAR_BALLOON_CLICK;