+\section{Log functions}\label{logfunctions}
+
+These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
+further information.
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\membersection{::wxLogError}\label{wxlogerror}
+
+\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
+
+The function to use for error messages, i.e. the
+messages that must be shown to the user. The default processing is to pop up a
+message box to inform the user about it.
+
+\membersection{::wxLogFatalError}\label{wxlogfatalerror}
+
+\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
+
+Like \helpref{wxLogError}{wxlogerror}, but also
+terminates the program with the exit code 3. Using {\it abort()} standard
+function also terminates the program with this exit code.
+
+\membersection{::wxLogWarning}\label{wxlogwarning}
+
+\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
+
+For warnings - they are also normally shown to the
+user, but don't interrupt the program work.
+
+\membersection{::wxLogMessage}\label{wxlogmessage}
+
+\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
+
+for all normal, informational messages. They also
+appear in a message box by default (but it can be changed). Notice
+that the standard behaviour is to not show informational messages if there are
+any errors later - the logic being that the later error messages make the
+informational messages preceding them meaningless.
+
+\membersection{::wxLogVerbose}\label{wxlogverbose}
+
+\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
+
+For verbose output. Normally, it's suppressed, but
+might be activated if the user wishes to know more details about the program
+progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
+
+\membersection{::wxLogStatus}\label{wxlogstatus}
+
+\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
+
+For status messages - they will go into the status
+bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one.
+
+\membersection{::wxLogSysError}\label{wxlogsyserror}
+
+\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
+
+Mostly used by wxWindows itself, but might be
+handy for logging errors after system call (API function) failure. It logs the
+specified message text as well as the last system error code ({\it errno} or {\it ::GetLastError()} depending
+on the platform) and the corresponding error
+message. The second form of this function takes the error code explitly as the
+first argument.
+
+\membersection{::wxLogDebug}\label{wxlogdebug}
+
+\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
+
+The right function for debug output. It only
+does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined)
+and expands to nothing in release mode (otherwise).
+
+\membersection{::wxLogTrace}\label{wxlogtrace}
+
+\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
+
+\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}}
+
+As {\bf wxLogDebug}, only does something in debug
+build. The reason for making it a separate function from it is that usually
+there are a lot of trace messages, so it might make sense to separate them
+from other debug messages which would be flooded in them. Moreover, the second
+version of this function takes a trace mask as the first argument which allows
+to further restrict the amount of messages generated. The value of {\it mask} can be:
+
+\begin{itemize}\itemsep=0pt
+\item wxTraceMemAlloc: trace memory allocation (new/delete)
+\item wxTraceMessages: trace window messages/X callbacks
+\item wxTraceResAlloc: trace GDI resource allocation
+\item wxTraceRefCount: trace various ref counting operations
+\end{itemize}
+
+\section{Debugging macros and functions}\label{debugmacros}
+
+Useful macros and functins for error checking and defensive programming. ASSERTs are only
+compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
+builds.
+
+\wxheading{Include files}
+
+<wx/debug.h>
+
+\membersection{::wxOnAssert}\label{wxonassert}
+
+\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
+
+This function may be redefined to do something non trivial and is called
+whenever one of debugging macros fails (i.e. condition is false in an
+assertion).
+% TODO: this should probably be an overridable in wxApp.
+
+\membersection{wxASSERT}\label{wxassert}
+
+\func{}{wxASSERT}{\param{}{condition}}
+
+Assert macro. An error message will be generated if the condition is FALSE in
+debug mode, but nothing will be done in the release build.
+
+Please note that the condition in wxASSERT() should have no side effects
+because it will not be executed in release mode at all.
+
+See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
+
+\membersection{wxASSERT\_MSG}\label{wxassertmsg}
+
+\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
+
+Assert macro with message. An error message will be generated if the condition is FALSE.
+
+See also: \helpref{wxASSERT}{wxassert}
+
+\membersection{wxFAIL}\label{wxfail}
+
+\func{}{wxFAIL}{\void}
+
+Will always generate an assert error if this code is reached (in debug mode).
+
+See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
+
+\membersection{wxFAIL\_MSG}\label{wxfailmsg}
+
+\func{}{wxFAIL\_MSG}{\param{}{msg}}
+
+Will always generate an assert error with specified message if this code is reached (in debug mode).
+
+This macro is useful for marking unreachable" code areas, for example
+it may be used in the "default:" branch of a switch statement if all possible
+cases are processed above.
+
+See also: \helpref{wxFAIL}{wxfail}
+
+\membersection{wxCHECK}\label{wxcheck}
+
+\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
+
+Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
+This check is done even in release mode.
+
+\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
+
+\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
+
+Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
+This check is done even in release mode.
+
+This macro may be only used in non void functions, see also
+\helpref{wxCHECK\_RET}{wxcheckret}.
+
+\membersection{wxCHECK\_RET}\label{wxcheckret}
+
+\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
+
+Checks that the condition is true, and returns if not (FAILs with given error
+message in debug mode). This check is done even in release mode.
+
+This macro should be used in void functions instead of
+\helpref{wxCHECK\_MSG}{wxcheckmsg}.
+
+\membersection{wxCHECK2}\label{wxcheck2}
+
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
+
+Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
+{\it operation} if it is not. This is a generalisation of
+\helpref{wxCHECK}{wxcheck} and may be used when something else than just
+returning from the function must be done when the {\it condition} is false.
+
+This check is done even in release mode.
+
+\membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
+
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
+
+This is the same as \helpref{wxCHECK2}{wxcheck2}, but
+\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
+instead of wxFAIL() if the {\it condition} is false.
+
projects / wxWidgets.git / blobdiff