X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1ec5cbf3de62355577408ced5017c1844c71edaf..10ff9c616e00e4074dfdc2ac9e354605cc129c22:/docs/latex/wx/log.tex?ds=inline diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex index fa31caabb9..7a606ef27c 100644 --- a/docs/latex/wx/log.tex +++ b/docs/latex/wx/log.tex @@ -11,7 +11,7 @@ \section{\class{wxLog}}\label{wxlog} -wxLog class defines the interface for the {\it log targets} used by wxWindows +wxLog class defines the interface for the {\it log targets} used by wxWidgets logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}. The only situations when you need to directly use this class is when you want to derive your own log target because the existing ones don't satisfy your @@ -23,7 +23,7 @@ completely) the timestamp on the messages. Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and you may not even know about its existence. -See \helpref{log overview}{wxlogoverview} for the descriptions of wxWindows +See \helpref{log overview}{wxlogoverview} for the descriptions of wxWidgets logging facilities. \wxheading{Derived from} @@ -34,9 +34,13 @@ No base class +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \latexignore{\rtfignore{\wxheading{Function groups}}} -\membersection{Static functions} +\membersection{Global functions} The functions in this section work with and manipulate the active log target. The \helpref{OnLog()}{wxlogonlog} is called by the {\it wxLogXXX()} functions @@ -54,7 +58,7 @@ situations because it may easily lead to a loss of messages. \helpref{Suspend}{wxlogsuspend}\\ \helpref{Resume}{wxlogresume} -\membersection{Logging functions} +\membersection{Logging functions}\label{loggingfunctions} There are two functions which must be implemented by any derived class to actually process the log messages: \helpref{DoLog}{wxlogdolog} and @@ -155,7 +159,9 @@ window on the corresponding error message. If you wish to enable it, please use \helpref{SetTimestamp}{wxlogsettimestamp}\\ \helpref{GetTimestamp}{wxloggettimestamp}\\ \helpref{SetTraceMask}{wxlogsettracemask}\\ -\helpref{GetTraceMask}{wxloggettracemask} +\helpref{GetTraceMask}{wxloggettracemask}\\ +\helpref{SetRepetitionCounting}{wxlogsetrepetitioncounting}\\ +\helpref{GetRepetitionCounting}{wxloggetrepetitioncounting} %%%%% MEMBERS HERE %%%%% \helponly{\insertatlevel{2}{ @@ -172,6 +178,7 @@ Add the {\it mask} to the list of allowed masks for \helpref{wxLogTrace}{wxlogtrace}. \wxheading{See also} + \helpref{RemoveTraceMask}{wxlogremovetracemask} \helpref{GetTraceMasks}{wxloggettracemasks} @@ -183,20 +190,22 @@ Removes all trace masks previously set with \helpref{AddTraceMask}{wxlogaddtracemask}. \wxheading{See also} + \helpref{RemoveTraceMask}{wxlogremovetracemask} \membersection{wxLog::GetTraceMasks}\label{wxloggettracemasks} -\func{static const wxArrayString &}{GetTraceMasks}{\void} +\func{static const wxArrayString \&}{GetTraceMasks}{\void} Returns the currently allowed list of string trace masks. \wxheading{See also} + \helpref{AddTraceMask}{wxlogaddtracemask}. \membersection{wxLog::OnLog}\label{wxlogonlog} -\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}} +\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const wxString\& }{ message}} Forwards the message at specified level to the {\it DoLog()} function of the active log target if there is any, does nothing otherwise. @@ -212,7 +221,9 @@ Returns the pointer to the active log target (may be NULL). \func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}} Sets the specified log target as the active one. Returns the pointer to the -previous active log target (may be NULL). +previous active log target (may be NULL). To suppress logging use a new +instance of wxLogNull not NULL. If the active log target is set to NULL a +new default log target will be created when logging occurs. \membersection{wxLog::Suspend}\label{wxlogsuspend} @@ -228,7 +239,7 @@ logging immediately without waiting for \helpref{Flush}{wxlogflush} to be called (the standard GUI log target only shows the log dialog when it is flushed, so Suspend() works as expected with it). -\wxheading{See also:} +\wxheading{See also} \helpref{Resume}{wxlogresume},\\ \helpref{wxLogNull}{wxlogoverview} @@ -243,7 +254,7 @@ flushed soon. \membersection{wxLog::DoLog}\label{wxlogdolog} -\func{virtual void}{DoLog}{\param{wxLogLevel }{level}, \param{const wxChar }{*msg}, \param{time\_t }{timestamp}} +\func{virtual void}{DoLog}{\param{wxLogLevel }{level}, \param{const wxString\& }{msg}, \param{time\_t }{timestamp}} Called to process the message of the specified severity. {\it msg} is the text of the message as specified in the call of {\it wxLogXXX()} function which @@ -255,9 +266,9 @@ corresponding to the log level and then calls \membersection{wxLog::DoLogString}\label{wxlogdologstring} -\func{virtual void}{DoLogString}{\param{const wxChar }{*msg}, \param{time\_t }{timestamp}} +\func{virtual void}{DoLogString}{\param{const wxString\& }{msg}, \param{time\_t }{timestamp}} -Called to log the specified string. The timestamp is already included into the +Called to log the specified string. The timestamp is already included in the string but still passed to this function. A simple implementation may just send the string to {\tt stdout} or, better, @@ -287,13 +298,13 @@ is already empty, nothing happens. Flushes the current log target if any, does nothing if there is none. -See also: +\wxheading{See also} \helpref{Flush}{wxlogflush} \membersection{wxLog::SetVerbose}\label{wxlogsetverbose} -\func{static void}{SetVerbose}{\param{bool }{ verbose = TRUE}} +\func{static void}{SetVerbose}{\param{bool }{ verbose = true}} Activates or deactivates verbose mode in which the verbose messages are logged as the normal ones instead of being silently dropped. @@ -317,18 +328,41 @@ and not sent to the active log target. Returns the current log level limit. +\membersection{wxLog::SetRepetitionCounting}\label{wxlogsetrepetitioncounting} + +\func{static void}{SetRepetitionCounting}{\param{bool }{ repetCounting = true}} + +Enables logging mode in which a log message is logged once, and in case exactly +the same message successively repeats one or more times, only the number of +repetitions is logged. + +\membersection{wxLog::GetRepetitionCounting}\label{wxloggetrepetitioncounting} + +\func{static bool}{GetRepetitionCounting}{\void} + +Returns whether the repetition counting mode is enabled. + + \membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp} -\func{void}{SetTimestamp}{\param{const char * }{ format}} +\func{static void}{SetTimestamp}{\param{const wxString\&}{ format}} Sets the timestamp format prepended by the default log targets to all messages. The string may contain any normal characters as well as \% prefixed format specificators, see {\it strftime()} manual for details. -Passing a NULL value (not empty string) to this function disables message timestamping. +Passing an empty string to this function disables message time stamping. + +\membersection{wxLog::DisableTimestamp}\label{wxlogdisabletimestamp} + +\func{void}{SetTimestamp}{\param{const wxString\&}{ format}} + +Disables time stamping of the log messages. + +\newsince{2.9} \membersection{wxLog::GetTimestamp}\label{wxloggettimestamp} -\constfunc{const char *}{GetTimestamp}{\void} +\func{static const wxString\&}{GetTimestamp}{\void} Returns the current timestamp format string. @@ -341,14 +375,16 @@ section for details. \membersection{wxLog::GetTraceMask}\label{wxloggettracemask} +\func{static wxTraceMask}{GetTraceMask}{\void} + Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section for details. \membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask} -\func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}} +\func{static bool}{IsAllowedTraceMask}{\param{const wxString\& }{mask}} -Returns TRUE if the {\it mask} is one of allowed masks for +Returns true if the {\it mask} is one of allowed masks for \helpref{wxLogTrace}{wxlogtrace}. See also: \helpref{AddTraceMask}{wxlogaddtracemask}, @@ -397,21 +433,32 @@ delete wxLog::SetActiveTarget(...something else or NULL...); +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogChain::wxLogChain}\label{wxlogchainwxlogchain} +\membersection{wxLogChain::wxLogChain}\label{wxlogchainctor} \func{}{wxLogChain}{\param{wxLog *}{logger}} Sets the specified {\tt logger} (which may be {\tt NULL}) as the default log target but the log messages are also passed to the previous log target if any. -\membersection{wxLogChain::\destruct{wxLogChain}} +\membersection{wxLogChain::\destruct{wxLogChain}}\label{wxlogchaindtor} \func{}{\destruct{wxLogChain}}{\void} Destroys the previous log target. +\membersection{wxLogChain::DetachOldLog}\label{wxlogchaindetacholdlog} + +\func{void}{DetachOldLog}{\void} + +Detaches the old log target so it won't be destroyed when the wxLogChain object +is destroyed. + \membersection{wxLogChain::GetOldLog}\label{wxlogchaingetoldlog} \constfunc{wxLog *}{GetOldLog}{\void} @@ -423,8 +470,8 @@ NULL}). \constfunc{bool}{IsPassingMessages}{\void} -Returns {\tt TRUE} if the messages are passed to the previously active log -target (default) or {\tt FALSE} if \helpref{PassMessages}{wxlogchainpassmessages} +Returns {\tt true} if the messages are passed to the previously active log +target (default) or {\tt false} if \helpref{PassMessages}{wxlogchainpassmessages} had been called. \membersection{wxLogChain::PassMessages}\label{wxlogchainpassmessages} @@ -432,17 +479,17 @@ had been called. \func{void}{PassMessages}{\param{bool }{passMessages}} By default, the log messages are passed to the previously active log target. -Calling this function with {\tt FALSE} parameter disables this behaviour +Calling this function with {\tt false} parameter disables this behaviour (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and it can be reenabled by calling it again with {\it passMessages} set to {\tt -TRUE}. +true}. \membersection{wxLogChain::SetLog}\label{wxlogchainsetlog} \func{void}{SetLog}{\param{wxLog *}{logger}} Sets another log target to use (may be {\tt NULL}). The log target specified -in the \helpref{constructor}{wxlogchainwxlogchain} or in a previous call to +in the \helpref{constructor}{wxlogchainctor} or in a previous call to this function is deleted. This doesn't change the old log target value (the one the messages are @@ -453,9 +500,9 @@ object was created. \section{\class{wxLogGui}}\label{wxloggui} -This is the default log target for the GUI wxWindows applications. It is passed +This is the default log target for the GUI wxWidgets applications. It is passed to \helpref{wxLog::SetActiveTarget}{wxlogsetactivetarget} at the program -startup and is deleted by wxWindows during the program shut down. +startup and is deleted by wxWidgets during the program shut down. \wxheading{Derived from} @@ -467,7 +514,7 @@ startup and is deleted by wxWindows during the program shut down. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogGui::wxLogGui} +\membersection{wxLogGui::wxLogGui}\label{wxlogguictor} \func{}{wxLogGui}{\void} @@ -480,7 +527,7 @@ Default constructor. This class allows to temporarily suspend logging. All calls to the log functions during the life time of an object of this class are just ignored. -In particular, it can be used to suppress the log messages given by wxWindows +In particular, it can be used to suppress the log messages given by wxWidgets itself but it should be noted that it is rarely the best way to cope with this problem as {\bf all} log messages are suppressed, even if they indicate a completely different error than the one the programmer wanted to suppress. @@ -500,7 +547,7 @@ For instance, the example of the overview: wxLogMessage("..."); // ok \end{verbatim} -} +}% would be better written as: @@ -520,7 +567,7 @@ would be better written as: ... } \end{verbatim} -} +}% \wxheading{Derived from} @@ -530,44 +577,86 @@ would be better written as: +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogNull::wxLogNull} +\membersection{wxLogNull::wxLogNull}\label{wxlognullctor} \func{}{wxLogNull}{\void} Suspends logging. -\membersection{wxLogNull::\destruct{wxLogNull}} +\membersection{wxLogNull::\destruct{wxLogNull}}\label{wxlognulldtor} Resumes logging. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogPassThrough %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogInterposer %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{\class{wxLogPassThrough}}\label{wxlogpassthrough} +\section{\class{wxLogInterposer}}\label{wxloginterposer} A special version of \helpref{wxLogChain}{wxlogchain} which uses itself as the -new log target. Maybe more clearly, it means that this is a log target which -forwards the log messages to the previously installed one in addition to +new log target. It forwards log messages to the previously installed one in addition to processing them itself. Unlike \helpref{wxLogChain}{wxlogchain} which is usually used directly as is, this class must be derived from to implement \helpref{DoLog}{wxlogdolog} and/or \helpref{DoLogString}{wxlogdologstring} methods. +wxLogInterposer destroys the previous log target in its destructor. If you +don't want this to happen, use wxLogInterposerTemp instead. + \wxheading{Derived from} -\helpref{wxLogChain}{wxlogchain} +\helpref{wxLogChain}{wxlogchain}\\ +\helpref{wxLog}{wxlog} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogPassThrough::wxLogPassThrough}\label{wxlogpassthroughctor} +\membersection{wxLogInterposer::wxLogInterposer}\label{wxloginterposerctor} + +The default constructor installs this object as the current active log target. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogInterposerTemp %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxLogInterposerTemp}}\label{wxloginterposertemp} + +A special version of \helpref{wxLogChain}{wxlogchain} which uses itself as the +new log target. It forwards log messages to the previously installed one in addition to +processing them itself. Unlike \helpref{wxLogInterposer}{wxloginterposer}, it doesn't +delete the old target which means it can be used to temporarily redirect log output. + +As per wxLogInterposer, this class must be derived from to implement \helpref{DoLog}{wxlogdolog} +and/or \helpref{DoLogString}{wxlogdologstring} methods. + +\wxheading{Derived from} -Default ctor installs this object as the current active log target. +\helpref{wxLogChain}{wxlogchain}\\ +\helpref{wxLog}{wxlog} + +\wxheading{Include files} + + + +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxLogInterposerTemp::wxLogInterposerTemp}\label{wxloginterposertempctor} + +The default constructor installs this object as the current active log target. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogStderr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -575,7 +664,7 @@ Default ctor installs this object as the current active log target. This class can be used to redirect the log messages to a C file stream (not to be confused with C++ streams). It is the default log target for the non-GUI -wxWindows applications which send all the output to {\tt stderr}. +wxWidgets applications which send all the output to {\tt stderr}. \wxheading{Derived from} @@ -585,13 +674,17 @@ wxWindows applications which send all the output to {\tt stderr}. +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxLogStream}{wxlogstream} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogStderr::wxLogStderr} +\membersection{wxLogStderr::wxLogStderr}\label{wxlogstderrctor} \func{}{wxLogStderr}{\param{FILE }{*fp = NULL}} @@ -604,7 +697,7 @@ Constructs a log target which sends all the log messages to the given This class can be used to redirect the log messages to a C++ stream. -Please note that this class is only available if wxWindows was compiled with +Please note that this class is only available if wxWidgets was compiled with the standard iostream library support ({\tt wxUSE\_STD\_IOSTREAM} must be on). \wxheading{Derived from} @@ -615,6 +708,10 @@ the standard iostream library support ({\tt wxUSE\_STD\_IOSTREAM} must be on). +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxLogStderr}{wxlogstderr},\\ @@ -622,7 +719,7 @@ the standard iostream library support ({\tt wxUSE\_STD\_IOSTREAM} must be on). \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogStream::wxLogStream} +\membersection{wxLogStream::wxLogStream}\label{wxlogstreamctor} \func{}{wxLogStream}{\param{std::ostream }{*ostr = NULL}} @@ -647,12 +744,12 @@ caller previously. \wxheading{See also} -\helpref{wxLogTextCtrl}{wxlogtextctrl},\\ +\helpref{wxTextCtrl}{wxtextctrl},\\ \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogTextCtrl::wxLogTextCtrl} +\membersection{wxLogTextCtrl::wxLogTextCtrl}\label{wxlogtextctrlctor} \func{}{wxLogTextCtrl}{\param{wxTextCtrl }{*textctrl}} @@ -671,7 +768,9 @@ them normally by showing the standard log dialog. \wxheading{Derived from} -\helpref{wxLogPassThrough}{wxlogpassthrough} +\helpref{wxLogInterposer}{wxloginterposer}\\ +\helpref{wxLogChain}{wxlogchain}\\ +\helpref{wxLog}{wxlog} \wxheading{Include files} @@ -683,9 +782,9 @@ them normally by showing the standard log dialog. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxLogWindow::wxLogWindow} +\membersection{wxLogWindow::wxLogWindow}\label{wxlogwindowctor} -\func{}{wxLogWindow}{\param{wxFrame }{*parent}, \param{const wxChar }{*title}, \param{bool }{show = {\tt TRUE}}, \param{bool }{passToOld = {\tt TRUE}}} +\func{}{wxLogWindow}{\param{wxFrame }{*parent}, \param{const wxChar }{*title}, \param{bool }{show = {\tt true}}, \param{bool }{passToOld = {\tt true}}} Creates the log frame window and starts collecting the messages in it. @@ -695,27 +794,27 @@ Creates the log frame window and starts collecting the messages in it. \docparam{title}{The title for the log frame} -\docparam{show}{{\tt TRUE} to show the frame initially (default), otherwise +\docparam{show}{{\tt true} to show the frame initially (default), otherwise \helpref{wxLogWindow::Show}{wxlogwindowshow} must be called later.} -\docparam{passToOld}{{\tt TRUE} to process the log messages normally in addition to -logging them in the log frame (default), {\tt FALSE} to only log them in the +\docparam{passToOld}{{\tt true} to process the log messages normally in addition to +logging them in the log frame (default), {\tt false} to only log them in the log frame.} \membersection{wxLogWindow::Show}\label{wxlogwindowshow} -\func{void}{Show}{\param{bool }{show = {\tt TRUE}}} +\func{void}{Show}{\param{bool }{show = {\tt true}}} Shows or hides the frame. -\membersection{wxLogWindow::GetFrame} +\membersection{wxLogWindow::GetFrame}\label{wxlogwindowgetframe} \constfunc{wxFrame *}{GetFrame}{\void} Returns the associated log frame window. This may be used to position or resize it but use \helpref{wxLogWindow::Show}{wxlogwindowshow} to show or hide it. -\membersection{wxLogWindow::OnFrameCreate} +\membersection{wxLogWindow::OnFrameCreate}\label{wxlogwindowonframecreate} \func{virtual void}{OnFrameCreate}{\param{wxFrame }{*frame}} @@ -724,13 +823,13 @@ any extra initializations. \membersection{wxLogWindow::OnFrameClose}\label{wxlogwindowonframeclose} -\func{virtual void}{OnFrameClose}{\param{wxFrame }{*frame}} +\func{virtual bool}{OnFrameClose}{\param{wxFrame }{*frame}} Called if the user closes the window interactively, will not be called if it is destroyed for another reason (such as when program exits). -Return {\tt TRUE} from here to allow the frame to close, {\tt FALSE} to +Return {\tt true} from here to allow the frame to close, {\tt false} to prevent this from happening. \wxheading{See also}