]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/taskbar.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxTaskBarIcon
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 This class represents a taskbar icon.
13 A taskbar icon is an icon that appears in the 'system tray' and responds to
14 mouse clicks, optionally with a tooltip above it to help provide information.
16 @section taskbaricon_xnote X Window System Note
17 Under X Window System, the window manager must support either the
18 "System Tray Protocol" (see http://freedesktop.org/wiki/Specifications/systemtray-spec)
19 by freedesktop.org (WMs used by modern desktop environments such as GNOME >= 2,
20 KDE >= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and KDE 1 and 2.
22 If it doesn't, the icon will appear as a toplevel window on user's desktop.
23 Because not all window managers have system tray, there's no guarantee that
24 wxTaskBarIcon will work correctly under X Window System and so the applications
25 should use it only as an optional component of their user interface.
26 The user should be required to explicitly enable the taskbar icon on Unix,
27 it shouldn't be on by default.
29 @beginEventTable{wxTaskBarIconEvent}
30 Note that not all ports are required to send these events and so it's better
31 to override wxTaskBarIcon::CreatePopupMenu() if all that the application does
32 is that it shows a popup menu in reaction to mouse click.
33 @event{EVT_TASKBAR_MOVE(func)}
34 Process a wxEVT_TASKBAR_MOVE event.
35 @event{EVT_TASKBAR_LEFT_DOWN(func)}
36 Process a wxEVT_TASKBAR_LEFT_DOWN event.
37 @event{EVT_TASKBAR_LEFT_UP(func)}
38 Process a wxEVT_TASKBAR_LEFT_UP event.
39 @event{EVT_TASKBAR_RIGHT_DOWN(func)}
40 Process a wxEVT_TASKBAR_RIGHT_DOWN event.
41 @event{EVT_TASKBAR_RIGHT_UP(func)}
42 Process a wxEVT_TASKBAR_RIGHT_UP event.
43 @event{EVT_TASKBAR_LEFT_DCLICK(func)}
44 Process a wxEVT_TASKBAR_LEFT_DCLICK event.
45 @event{EVT_TASKBAR_RIGHT_DCLICK(func)}
46 Process a wxEVT_TASKBAR_RIGHT_DCLICK event.
47 @event{EVT_TASKBAR_CLICK(func)}
48 This is a synonym for either EVT_TASKBAR_RIGHT_DOWN or UP depending on
49 the platform, use this event macro to catch the event which should result
50 in the menu being displayed on the current platform.
56 class wxTaskBarIcon
: public wxEvtHandler
65 Destroys the wxTaskBarIcon object, removing the icon if not already removed.
67 virtual ~wxTaskBarIcon();
70 This method is similar to wxWindow::Destroy and can be used to schedule
71 the task bar icon object for the delayed destruction: it will be deleted
72 during the next event loop iteration, which allows the task bar
73 icon to process any pending events for it before being destroyed.
78 Returns @true if SetIcon() was called with no subsequent RemoveIcon().
80 bool IsIconInstalled() const;
83 Returns @true if the object initialized successfully.
88 Pops up a menu at the current mouse position.
89 The events can be handled by a class derived from wxTaskBarIcon.
92 It is recommended to override CreatePopupMenu() callback instead of
93 calling this method from event handler, because some ports (e.g. wxCocoa)
94 may not implement PopupMenu() and mouse click events at all.
96 virtual bool PopupMenu(wxMenu
* menu
);
99 Removes the icon previously set with SetIcon().
101 virtual bool RemoveIcon();
104 Sets the icon, and optional tooltip text.
106 virtual bool SetIcon(const wxIcon
& icon
,
107 const wxString
& tooltip
= wxEmptyString
);
110 Returns true if system tray is available in the desktop environment the
113 On Windows and Mac OS X, the tray is always available and this function
116 On Unix, X11 environment may or may not provide the tray, depending on
117 user's desktop environment. Most modern desktops support the tray via
118 the System Tray Protocol by freedesktop.org
119 (http://freedesktop.org/wiki/Specifications/systemtray-spec).
121 @note Tray availability may change during application's lifetime
122 under X11 and so applications shouldn't cache the result.
124 @note wxTaskBarIcon supports older GNOME 1.2 and KDE 1/2 methods of
125 adding icons to tray, but they are unreliable and this method
130 static bool IsAvailable();
135 This method is called by the library when the user requests popup menu
136 (on Windows and Unix platforms, this is when the user right-clicks the icon).
138 Override this function in order to provide popup menu associated with the icon.
139 If CreatePopupMenu() returns @NULL (this happens by default), no menu is shown,
140 otherwise the menu is displayed and then deleted by the library as soon as the
143 The events can be handled by a class derived from wxTaskBarIcon.
145 virtual wxMenu
* CreatePopupMenu();