X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ea64fd024a209dc3048d953e9e048d6a73a02220..097119648b492237f16acdf484eff8900c7c94d2:/docs/latex/wx/taskbar.tex diff --git a/docs/latex/wx/taskbar.tex b/docs/latex/wx/taskbar.tex index 0860f26b47..073247e548 100644 --- a/docs/latex/wx/taskbar.tex +++ b/docs/latex/wx/taskbar.tex @@ -1,7 +1,22 @@ \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} @@ -12,10 +27,17 @@ mouse clicks. An icon has an optional tooltip. This class is only supported for +\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. +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 @@ -33,75 +55,81 @@ wxEVT\_TASKBAR\_RIGHT\_UP event.} 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}}} -\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconconstr} + +\membersection{wxTaskBarIcon::wxTaskBarIcon}\label{wxtaskbariconctor} \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. -\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} +\membersection{wxTaskBarIcon::CreatePopupMenu}\label{wxtaskbariconcreatepopupmenu} -\func{bool}{IsOK}{\void} +\func{virtual wxMenu*}{CreatePopupMenu}{\void} -Returns TRUE if the object initialized successfully. +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. -\membersection{wxTaskBarIcon::OnLButtonDown}\label{wxtaskbaricononlbuttondown} +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. -\func{virtual void}{OnLButtonDown}{\void} -Override this function to intercept left mouse button down events. +\membersection{wxTaskBarIcon::Destroy}\label{wxtaskbaricondestroy} -\membersection{wxTaskBarIcon::OnLButtonDClick}\label{wxtaskbaricononlbuttondclick} +\func{void}{Destroy}{\void} -\func{virtual void}{OnLButtonDClick}{\void} +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. -Override this function to intercept left mouse button double-click events. -\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} @@ -109,6 +137,7 @@ Override this function to intercept mouse move events. 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}}