API change: a single SELECTION_CHANGED not lots of SELECT and UNSELECT events

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

diff --git a/docs/latex/wx/taskbar.tex b/docs/latex/wx/taskbar.tex
index f6a81a428860ea5344bbf856372eb194da2cfee6..073247e548c4810dd2e88100fdd484afe4cedb97 100644 (file)
--- a/docs/latex/wx/taskbar.tex
+++ b/docs/latex/wx/taskbar.tex
@@ -1,79 +1,135 @@
 \section{\class{wxTaskBarIcon}}\label{wxtaskbaricon}
 
 \section{\class{wxTaskBarIcon}}\label{wxtaskbaricon}
 

-This class represents a Windows 95 taskbar icon, appearing in the `system tray' and responding to
-mouse clicks. An icon has an optional tooltip. This class is only supported for Windows 95/NT.
+This class represents a taskbar icon. A taskbar icon is an icon that appears in the `system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information.
+
+\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}
 
 
 \wxheading{Derived from}
 

+\helpref{wxEvtHandler}{wxevthandler}\\

 \helpref{wxObject}{wxobject}
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/taskbar.h>
+
+\wxheading{Library}
+
+\helpref{wxAdv}{librarieslist}
+
+\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.}
+\twocolitem{{\bf EVT\_TASKBAR\_CLICK(func)}}{This is a synonym for either
+EVT\_TASKBAR\_RIGHT\_DOWN or UP depending on the platform, use this event macro
+to catch the event which should result in the menu being displayed on the
+current platform.}
+\end{twocollist}%
+

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

-\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconconstr}
+
+\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconctor}

 
 \func{}{wxTaskBarIcon}{\void}
 
 Default constructor.
 
 
 \func{}{wxTaskBarIcon}{\void}
 
 Default constructor.
 

-\membersection{wxTaskBarIcon::\destruct{wxTaskBarIcon}}
+
+\membersection{wxTaskBarIcon::\destruct{wxTaskBarIcon}}\label{wxtaskbaricondtor}

 
 \func{}{\destruct{wxTaskBarIcon}}{\void}
 
 Destroys the wxTaskBarIcon object, removing the icon if not already removed.
 
 
 \func{}{\destruct{wxTaskBarIcon}}{\void}
 
 Destroys the wxTaskBarIcon object, removing the icon if not already removed.
 

-\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}
+\membersection{wxTaskBarIcon::CreatePopupMenu}\label{wxtaskbariconcreatepopupmenu}

 
 

-Returns TRUE if the object initialized successfully.
+\func{virtual wxMenu*}{CreatePopupMenu}{\void}

 
 

-\membersection{wxTaskBarIcon::OnLButtonDown}\label{wxtaskbaricononlbuttondown}
+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.

 
 

-\func{virtual void}{OnLButtonDown}{\void}
+If CreatePopupMenu 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.

 
 

-Override this function to intercept left mouse button down events.

 
 

-\membersection{wxTaskBarIcon::OnLButtonDClick}\label{wxtaskbaricononlbuttondclick}
+\membersection{wxTaskBarIcon::Destroy}\label{wxtaskbaricondestroy}

 
 

-\func{virtual void}{OnLButtonDClick}{\void}
+\func{void}{Destroy}{\void}

 
 

-Override this function to intercept left mouse button double-click events.
+This method is similar to \helpref{wxWindow::Destroy}{wxwindowdestroy} and can
+be used to schedule the task bar icon object for the delayed destruction: it
+will be deleted during the next event loop iteration, which allows the task bar
+icon to process any pending events for it before being destroyed.

 
 

-\membersection{wxTaskBarIcon::OnLButtonUp}\label{wxtaskbaricononlbuttonup}

 
 

-\func{virtual void}{OnLButtonUp}{\void}
+\membersection{wxTaskBarIcon::IsIconInstalled}\label{wxtaskbariconisiconinstalled}

 
 

-Override this function to intercept left mouse button up events.
+\func{bool}{IsIconInstalled}{\void}

 
 

-\membersection{wxTaskBarIcon::OnRButtonDown}\label{wxtaskbaricononrbuttondown}
+Returns true if \helpref{SetIcon}{wxtaskbariconseticon} was called with no subsequent \helpref{RemoveIcon}{wxtaskbariconremoveicon}.

 
 

-\func{virtual void}{OnRButtonDown}{\void}

 
 

-Override this function to intercept right mouse button down events.
+\membersection{wxTaskBarIcon::IsOk}\label{wxtaskbariconisok}

 
 

-\membersection{wxTaskBarIcon::OnRButtonDClick}\label{wxtaskbaricononrbuttondclick}
+\func{bool}{IsOk}{\void}

 
 

-\func{virtual void}{OnRButtonDClick}{\void}
+Returns true if the object initialized successfully.

 
 

-Override this function to intercept right mouse button double-click events.

 
 

-\membersection{wxTaskBarIcon::OnRButtonUp}\label{wxtaskbaricononrbuttonup}
+\membersection{wxTaskBarIcon::PopupMenu}\label{wxtaskbariconpopupmenu}

 
 

-\func{virtual void}{OnRButtonUp}{\void}
+\func{bool}{PopupMenu}{\param{wxMenu*}{ menu}}

 
 

-Override this function to intercept right mouse button up events.
+Pops up a menu at the current mouse position. The events can be handled by
+a class derived from wxTaskBarIcon.

 
 

-\membersection{wxTaskBarIcon::OnMouseMove}\label{wxtaskbaricononmousemove}
+\wxheading{Note}

 
 

-\func{virtual void}{OnMouseMove}{\void}
+It is recommended to override
+\helpref{CreatePopupMenu}{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.

 
 

-Override this function to intercept mouse move events.

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


@@ -81,6 +137,7 @@ Override this function to intercept mouse move events.
 
 Removes the icon previously set with \helpref{SetIcon}{wxtaskbariconseticon}.
 
 
 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}}
 \membersection{wxTaskBarIcon::SetIcon}\label{wxtaskbariconseticon}
 
 \func{bool}{SetIcon}{\param{const wxIcon\&}{ icon}, \param{const wxString\& }{tooltip}}