git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

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