[wxWidgets.git] / docs / latex / wx / taskbar.tex

\section{\class{wxTaskBarIcon}}\label{wxtaskbaricon}

This class represents a taskbar icon, appearing in the `system tray' and
responding to mouse clicks. An icon has an optional tooltip. This class is only
supported under Windows 95/NT and in X Window System ports (wxGTK, wxMotif,
wxX11). 

\wxheading{X Window System Note}

Under X Window System, the window manager must support either
the \urlref{System Tray Protocol by freedesktop.org}{http://freedesktop.org/Standards/systemtray-spec}
(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.


\wxheading{Derived from}

\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/taskbar.h>

\wxheading{Event handling}

To process input from a taskbar icon, use the following event handler macros to direct input to member
functions that take a wxTaskBarIconEvent argument. Note that not all ports are
required to send these events and so it's better to override
\helpref{CreatePopupMenu}{wxtaskbariconcreatepopupmenu} if all that
the application does is that it shows a popup menu in reaction to mouse click.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_TASKBAR\_MOVE(func)}}{Process a
wxEVT\_TASKBAR\_MOVE event.}
\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_DOWN(func)}}{Process a
wxEVT\_TASKBAR\_LEFT\_DOWN event.}
\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_UP(func)}}{Process a
wxEVT\_TASKBAR\_LEFT\_UP event.}
\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_DOWN(func)}}{Process a
wxEVT\_TASKBAR\_RIGHT\_DOWN event.}
\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_UP(func)}}{Process a
wxEVT\_TASKBAR\_RIGHT\_UP event.}
\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_DCLICK(func)}}{Process a
wxEVT\_TASKBAR\_LEFT\_DCLICK event.}
\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_DCLICK(func)}}{Process a
wxEVT\_TASKBAR\_RIGHT\_DCLICK event.}
\end{twocollist}%

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconconstr}

\func{}{wxTaskBarIcon}{\void}

Default constructor.

\membersection{wxTaskBarIcon::\destruct{wxTaskBarIcon}}

\func{}{\destruct{wxTaskBarIcon}}{\void}

Destroys the wxTaskBarIcon object, removing the icon if not already removed.

\membersection{wxTaskBarIcon::CreatePopupMenu}\label{wxtaskbariconcreatepopupmenu}

\func{virtual wxMenu*}{CreatePopupMenu}{\void}

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 CreatePopupIcon 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.

\membersection{wxTaskBarIcon::IsIconInstalled}\label{wxtaskbariconisiconinstalled}

\func{bool}{IsIconInstalled}{\void}

Returns true if \helpref{SetIcon}{wxtaskbariconseticon} was called with no subsequent \helpref{RemoveIcon}{wxtaskbariconremoveicon}.

\membersection{wxTaskBarIcon::IsOk}\label{wxtaskbariconisok}

\func{bool}{IsOk}{\void}

Returns true if the object initialized successfully.

\membersection{wxTaskBarIcon::PopupMenu}\label{wxtaskbariconpopupmenu}

\func{bool}{PopupMenu}{\param{wxMenu*}{ menu}}

Pops up a menu at the current mouse position. The events can be handled by
a class derived from wxTaskBarIcon.

\wxheading{Note}

It is recommended to override
\helpref{CreatePopupIcon}{wxtaskbariconcreatepopupmenu}
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.

\membersection{wxTaskBarIcon::RemoveIcon}\label{wxtaskbariconremoveicon}

\func{bool}{RemoveIcon}{\void}

Removes the icon previously set with \helpref{SetIcon}{wxtaskbariconseticon}.

\membersection{wxTaskBarIcon::SetIcon}\label{wxtaskbariconseticon}

\func{bool}{SetIcon}{\param{const wxIcon\&}{ icon}, \param{const wxString\& }{tooltip}}

Sets the icon, and optional tooltip text.
Commit	Line	Data
a660d684 KB	1	\section{\class{wxTaskBarIcon}}\label{wxtaskbaricon}
a660d684 KB	2
33d4eef0 VS	3	This class represents a taskbar icon, appearing in the `system tray' and
	4	responding to mouse clicks. An icon has an optional tooltip. This class is only
	5	supported under Windows 95/NT and in X Window System ports (wxGTK, wxMotif,
	6	wxX11).
	7
	8	\wxheading{X Window System Note}
	9
	10	Under X Window System, the window manager must support either
	11	the \urlref{System Tray Protocol by freedesktop.org}{http://freedesktop.org/Standards/systemtray-spec}
	12	(WMs used by modern desktop environments such as GNOME >= 2, KDE
	13	>= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and
	14	KDE 1 and 2. If it doesn't, the icon will appear as a toplevel window on
	15	user's desktop.
	16
	17	Because not all window managers have system tray, there's no guarantee that
	18	wxTaskBarIcon will work correctly under X Window System and so the applications
	19	should use it only as an optional component of their user interface. The user
	20	should be required to explicitly enable the taskbar icon on Unix, it shouldn't
	21	be on by default.
	22
a660d684 KB	23
	24	\wxheading{Derived from}
	25
ea64fd02	26	\helpref{wxEvtHandler}{wxevthandler}\\
a660d684 KB	27	\helpref{wxObject}{wxobject}
a660d684 KB	28
954b8ae6 JS	29	\wxheading{Include files}
	30
	31	<wx/taskbar.h>
	32
ea64fd02 MB	33	\wxheading{Event handling}
	34
	35	To process input from a taskbar icon, use the following event handler macros to direct input to member
dae73d74 VS	36	functions that take a wxTaskBarIconEvent argument. Note that not all ports are
	37	required to send these events and so it's better to override
	38	\helpref{CreatePopupMenu}{wxtaskbariconcreatepopupmenu} if all that
	39	the application does is that it shows a popup menu in reaction to mouse click.
ea64fd02 MB	40
	41	\twocolwidtha{7cm}
	42	\begin{twocollist}\itemsep=0pt
	43	\twocolitem{{\bf EVT\_TASKBAR\_MOVE(func)}}{Process a
	44	wxEVT\_TASKBAR\_MOVE event.}
	45	\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_DOWN(func)}}{Process a
	46	wxEVT\_TASKBAR\_LEFT\_DOWN event.}
	47	\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_UP(func)}}{Process a
	48	wxEVT\_TASKBAR\_LEFT\_UP event.}
	49	\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_DOWN(func)}}{Process a
	50	wxEVT\_TASKBAR\_RIGHT\_DOWN event.}
	51	\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_UP(func)}}{Process a
	52	wxEVT\_TASKBAR\_RIGHT\_UP event.}
	53	\twocolitem{{\bf EVT\_TASKBAR\_LEFT\_DCLICK(func)}}{Process a
	54	wxEVT\_TASKBAR\_LEFT\_DCLICK event.}
	55	\twocolitem{{\bf EVT\_TASKBAR\_RIGHT\_DCLICK(func)}}{Process a
	56	wxEVT\_TASKBAR\_RIGHT\_DCLICK event.}
	57	\end{twocollist}%
	58
a660d684 KB	59	\latexignore{\rtfignore{\wxheading{Members}}}
	60
	61	\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconconstr}
	62
	63	\func{}{wxTaskBarIcon}{\void}
	64
	65	Default constructor.
	66
	67	\membersection{wxTaskBarIcon::\destruct{wxTaskBarIcon}}
	68
	69	\func{}{\destruct{wxTaskBarIcon}}{\void}
	70
	71	Destroys the wxTaskBarIcon object, removing the icon if not already removed.
	72
dae73d74 VS	73	\membersection{wxTaskBarIcon::CreatePopupMenu}\label{wxtaskbariconcreatepopupmenu}
	74
	75	\func{virtual wxMenu*}{CreatePopupMenu}{\void}
	76
	77	This method is called by the library when the user requests popup menu
	78	(on Windows and Unix platforms, this is when the user right-clicks the icon).
	79	Override this function in order to provide popup menu associated with the icon.
	80
	81	If CreatePopupIcon returns NULL (this happens by default),
	82	no menu is shown, otherwise the menu is
	83	displayed and then deleted by the library as soon as the user dismisses it.
	84	The events can be handled by a class derived from wxTaskBarIcon.
	85
a660d684 KB	86	\membersection{wxTaskBarIcon::IsIconInstalled}\label{wxtaskbariconisiconinstalled}
	87
	88	\func{bool}{IsIconInstalled}{\void}
	89
cc81d32f	90	Returns true if \helpref{SetIcon}{wxtaskbariconseticon} was called with no subsequent \helpref{RemoveIcon}{wxtaskbariconremoveicon}.
a660d684	91
6af507f7	92	\membersection{wxTaskBarIcon::IsOk}\label{wxtaskbariconisok}
a660d684	93
6af507f7	94	\func{bool}{IsOk}{\void}
a660d684	95
cc81d32f	96	Returns true if the object initialized successfully.
a660d684	97
feb68562 JS	98	\membersection{wxTaskBarIcon::PopupMenu}\label{wxtaskbariconpopupmenu}
	99
	100	\func{bool}{PopupMenu}{\param{wxMenu*}{ menu}}
	101
	102	Pops up a menu at the current mouse position. The events can be handled by
	103	a class derived from wxTaskBarIcon.
	104
dae73d74 VS	105	\wxheading{Note}
	106
	107	It is recommended to override
	108	\helpref{CreatePopupIcon}{wxtaskbariconcreatepopupmenu}
	109	callback instead of calling this method from event handler, because some
	110	ports (e.g. wxCocoa) may not implement PopupMenu and mouse click events at all.
	111
a660d684 KB	112	\membersection{wxTaskBarIcon::RemoveIcon}\label{wxtaskbariconremoveicon}
	113
	114	\func{bool}{RemoveIcon}{\void}
	115
	116	Removes the icon previously set with \helpref{SetIcon}{wxtaskbariconseticon}.
	117
	118	\membersection{wxTaskBarIcon::SetIcon}\label{wxtaskbariconseticon}
	119
	120	\func{bool}{SetIcon}{\param{const wxIcon\&}{ icon}, \param{const wxString\& }{tooltip}}
	121
	122	Sets the icon, and optional tooltip text.
	123
	124