interface/wx/taskbar.h

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