no changes, just come cleanup and more comments

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        notifmsg.tex
%% Purpose:     wxNotificationMessage documentation
%% Author:      Vadim Zeitlin
%% Created:     2007-11-24
%% RCS-ID:      $Id$
%% Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwidgets.org>
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxNotificationMessage}}\label{wxnotificationmessage}

This class allows to show the user a message non intrusively. Currently it is
implemented natively only for the Maemo platform and uses (non-modal) dialogs
for the display of the notifications under the other platforms but it will be
extended to use the platform-specific notifications in the other ports in the
future.

Notice that this class is not a window and so doesn't derive from wxWindow.

\wxheading{Derived from}

\helpref{wxEvtHandler}{wxevthandler}

\wxheading{Include files}

<wx/notifmsg.h>

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


\membersection{wxNotificationMessage::wxNotificationMessage}\label{wxnotificationmessagewxnotificationmessage}

\func{}{wxNotificationMessage}{\void}

Default constructor, use \helpref{SetParent}{wxnotificationmessagesetparent}, 
\helpref{SetTitle}{wxnotificationmessagesettitle} and 
\helpref{SetMessage}{wxnotificationmessagesetmessage} to initialize the object
before showing it.


\func{}{wxNotificationMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{message = wxString()}, \param{wxWindow* }{parent = NULL}, \param{int }{flags = \texttt{wxICON\_INFORMATION}}}

Create a notification object with the given attributes.

See \helpref{SetTitle}{wxnotificationmessagesettitle}, 
\helpref{SetMessage}{wxnotificationmessagesetmessage}, 
\helpref{SetParent}{wxnotificationmessagesetparent} and
\helpref{SetFlags}{wxnotificationmessagesetflags} for the description of the
corresponding parameters.


\membersection{wxNotificationMessage::Close}\label{wxnotificationmessageclose}

\func{bool}{Close}{\void}

Hides the notification.

Returns \true if it was hidden or \false if it couldn't be done (e.g. on some
systems automatically hidden notifications can't be hidden manually)


\membersection{wxNotificationMessage::SetFlags}\label{wxnotificationmessagesetflags}

\func{void}{SetFlags}{\param{int }{flags}}

This parameter can be currently used to specify the icon to show in the
notification. Valid values are \texttt{wxICON\_INFORMATION}, 
\texttt{wxICON\_WARNING} and \texttt{wxICON\_ERROR} (notice that 
\texttt{wxICON\_QUESTION} is not allowed here).

Some implementations of this class may not support the icons.


\membersection{wxNotificationMessage::SetMessage}\label{wxnotificationmessagesetmessage}

\func{void}{SetMessage}{\param{const wxString\& }{message}}

Set the main text of the notification. This should be a more detailed
description than the title but still limited to reasonable length (not more
than 256 characters).


\membersection{wxNotificationMessage::SetParent}\label{wxnotificationmessagesetparent}

\func{void}{SetParent}{\param{wxWindow* }{parent}}

Set the parent for this notification: the notification will be associated with
the top level parent of this window or, if this method is not called, with the
main application window by default


\membersection{wxNotificationMessage::SetTitle}\label{wxnotificationmessagesettitle}

\func{void}{SetTitle}{\param{const wxString\& }{title}}

Set the title, it must be a concise string (not more than 64 characters), use 
\helpref{SetMessage}{wxnotificationmessagesetmessage} to give the user more
details.


\membersection{wxNotificationMessage::Show}\label{wxnotificationmessageshow}

\func{bool}{Show}{\param{int }{timeout = Timeout\_Auto}}

Show the notification to the user and hides it after timeout seconds
pass. Special values \texttt{Timeout\_Auto} and \texttt{Timeout\_Never} can be
used here, notice that you shouldn't rely on \arg{timeout} being exactly
respected because the current platform may only support default timeout value
and also because the user may be able to close the notification.

Returns \false if an error occurred.