// Global functions/macros
// ============================================================================
+/** @ingroup group_funcmacro_log */
+//@{
+
/**
- This function shows a message to the user in a safe way and should be safe to
- call even before the application has been initialized or if it is currently in
- some other strange state (for example, about to crash). Under Windows this
- function shows a message box using a native dialog instead of
- wxMessageBox() (which might be unsafe to call), elsewhere
- it simply prints the message to the standard output using the title as prefix.
+ This function shows a message to the user in a safe way and should be safe
+ to call even before the application has been initialized or if it is
+ currently in some other strange state (for example, about to crash). Under
+ Windows this function shows a message box using a native dialog instead of
+ wxMessageBox() (which might be unsafe to call), elsewhere it simply prints
+ the message to the standard output using the title as prefix.
@param title
- The title of the message box shown to the user or the prefix
- of the message string
+ The title of the message box shown to the user or the prefix of the
+ message string.
@param text
- The text to show to the user
+ The text to show to the user.
@see wxLogFatalError()
+
+ @header{wx/log.h}
*/
-void wxSafeShowMessage(const wxString& title,
- const wxString& text);
+void wxSafeShowMessage(const wxString& title, const wxString& text);
+
+/**
+ Returns the error code from the last system call. This function uses
+ @c errno on Unix platforms and @c GetLastError under Win32.
+ @see wxSysErrorMsg(), wxLogSysError()
+ @header{wx/log.h}
+*/
+unsigned long wxSysErrorCode();
+/**
+ Returns the error message corresponding to the given system error code. If
+ @a errCode is 0 (default), the last error code (as returned by
+ wxSysErrorCode()) is used.
+
+ @see wxSysErrorCode(), wxLogSysError()
+
+ @header{wx/log.h}
+*/
+const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
+
+//@}
+
+/** @ingroup group_funcmacro_log */
//@{
/**
- For all normal, informational messages. They also appear in a message box by
- default (but it can be changed).
+ For all normal, informational messages. They also appear in a message box
+ by default (but it can be changed).
+
+ @header{wx/log.h}
*/
void wxLogMessage(const char* formatString, ... );
void wxVLogMessage(const char* formatString, va_list argPtr);
//@}
+/** @ingroup group_funcmacro_log */
//@{
/**
- For verbose output. Normally, it is 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 @b
- wxLogInfo).
+ For verbose output. Normally, it is 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 could be @c wxLogInfo).
+
+ @header{wx/log.h}
*/
void wxLogVerbose(const char* formatString, ... );
void wxVLogVerbose(const char* formatString, va_list argPtr);
//@}
+/** @ingroup group_funcmacro_log */
//@{
/**
- For warnings - they are also normally shown to the user, but don't interrupt
- the program work.
+ For warnings - they are also normally shown to the user, but don't
+ interrupt the program work.
+
+ @header{wx/log.h}
*/
void wxLogWarning(const char* formatString, ... );
void wxVLogWarning(const char* formatString, va_list argPtr);
//@}
+/** @ingroup group_funcmacro_log */
//@{
/**
- Like wxLogError(), but also
- terminates the program with the exit code 3. Using @e abort() standard
- function also terminates the program with this exit code.
+ Like wxLogError(), but also terminates the program with the exit code 3.
+ Using @e abort() standard function also terminates the program with this
+ exit code.
+
+ @header{wx/log.h}
*/
void wxLogFatalError(const char* formatString, ... );
-void wxVLogFatalError(const char* formatString,
- va_list argPtr);
+void wxVLogFatalError(const char* formatString, va_list argPtr);
//@}
+/** @ingroup group_funcmacro_log */
//@{
/**
- The functions 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.
+ The functions 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.
+
+ @header{wx/log.h}
*/
void wxLogError(const char* formatString, ... );
void wxVLogError(const char* formatString, va_list argPtr);
//@}
-
+/** @ingroup group_funcmacro_log */
//@{
/**
- As @b wxLogDebug, trace functions only do something in debug build and
- expand to nothing in the release one. 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.
- The trace messages also usually can be separated into different categories and
- the second and third versions of this function only log the message if the
- @a mask which it has is currently enabled in wxLog. This
- allows to selectively trace only some operations and not others by changing
- the value of the trace mask (possible during the run-time).
- For the second function (taking a string mask), the message is logged only if
- the mask has been previously enabled by the call to
- wxLog::AddTraceMask or by setting
- @ref overview_envvars "@c WXTRACE environment variable".
- The predefined string trace masks
- used by wxWidgets are:
- wxTRACE_MemAlloc: trace memory allocation (new/delete)
- wxTRACE_Messages: trace window messages/X callbacks
- wxTRACE_ResAlloc: trace GDI resource allocation
- wxTRACE_RefCount: trace various ref counting operations
- wxTRACE_OleCalls: trace OLE method calls (Win32 only)
- @b Caveats: since both the mask and the format string are strings,
- this might lead to function signature confusion in some cases:
- if you intend to call the format string only version of wxLogTrace,
- then add a %s format string parameter and then supply a second string parameter
- for that %s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function.
- In this case you'll unfortunately have to avoid having two leading
- string parameters, e.g. by adding a bogus integer (with its %d format string).
- The third version of the function only logs the message if all the bits
- corresponding to the @a mask are set in the wxLog trace mask which can be
- set by wxLog::SetTraceMask. This version is less
- flexible than the previous one because it doesn't allow defining the user
- trace masks easily - this is why it is deprecated in favour of using string
- trace masks.
- wxTraceMemAlloc: trace memory allocation (new/delete)
- wxTraceMessages: trace window messages/X callbacks
- wxTraceResAlloc: trace GDI resource allocation
- wxTraceRefCount: trace various ref counting operations
- wxTraceOleCalls: trace OLE method calls (Win32 only)
+ Like wxLogDebug(), trace functions only do something in debug builds and
+ expand to nothing in the release one. The reason for making it a separate
+ function is that usually there are a lot of trace messages, so it might
+ make sense to separate them from other debug messages.
+
+ wxLogDebug(const char*,const char*,...) and
+ wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would
+ like to be able to separate trace messages into different categories which
+ can be enabled or disabled with the static functions provided in wxLog.
+
+ @header{wx/log.h}
*/
void wxLogTrace(const char* formatString, ... );
void wxVLogTrace(const char* formatString, va_list argPtr);
-void wxLogTrace(const char* mask, const char* formatString,
- ... );
+//@}
+
+/** @ingroup group_funcmacro_log */
+//@{
+/**
+ Like wxLogDebug(), trace functions only do something in debug builds and
+ expand to nothing in the release one. The reason for making it a separate
+ function is that usually there are a lot of trace messages, so it might
+ make sense to separate them from other debug messages.
+
+ In this version of wxLogTrace(), trace messages can be separated into
+ different categories and calls using this function only log the message if
+ the given @a mask is currently enabled in wxLog. This lets you selectively
+ trace only some operations and not others by enabling the desired trace
+ masks with wxLog::AddTraceMask() or by setting the
+ @ref overview_envvars "@c WXTRACE environment variable".
+
+ The predefined string trace masks used by wxWidgets are:
+
+ @beginDefList
+ @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) }
+ @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks }
+ @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation }
+ @itemdef{ wxTRACE_RefCount, Trace various ref counting operations }
+ @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
+ @endDefList
+
+ @note Since both the mask and the format string are strings, this might
+ lead to function signature confusion in some cases: if you intend to
+ call the format string only version of wxLogTrace(), add a "%s"
+ format string parameter and then supply a second string parameter for
+ that "%s", the string mask version of wxLogTrace() will erroneously
+ get called instead, since you are supplying two string parameters to
+ the function. In this case you'll unfortunately have to avoid having
+ two leading string parameters, e.g. by adding a bogus integer (with
+ its "%d" format string).
+
+ @header{wx/log.h}
+*/
+void wxLogTrace(const char* mask, const char* formatString, ... );
void wxVLogTrace(const char* mask,
- const char* formatString,
- va_list argPtr);
-void wxLogTrace(wxTraceMask mask, const char* formatString,
- ... );
-void wxVLogTrace(wxTraceMask mask, const char* formatString,
- va_list argPtr);
+ const char* formatString,
+ va_list argPtr);
//@}
+/** @ingroup group_funcmacro_log */
+//@{
+/**
+ Like wxLogDebug(), trace functions only do something in debug builds and
+ expand to nothing in the release one. The reason for making it a separate
+ function is that usually there are a lot of trace messages, so it might
+ make sense to separate them from other debug messages.
+
+ This version of wxLogTrace() only logs the message if all the bits
+ corresponding to the @a mask are set in the wxLog trace mask which can be
+ set by calling wxLog::SetTraceMask(). This version is less flexible than
+ wxLogDebug(const char*,const char*,...) because it doesn't allow defining
+ the user trace masks easily. This is why it is deprecated in favour of
+ using string trace masks.
+
+ The following bitmasks are defined for wxTraceMask:
+
+ @beginDefList
+ @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) }
+ @itemdef{ wxTraceMessages, Trace window messages/X callbacks }
+ @itemdef{ wxTraceResAlloc, Trace GDI resource allocation }
+ @itemdef{ wxTraceRefCount, Trace various ref counting operations }
+ @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) }
+ @endDefList
+
+ @header{wx/log.h}
+*/
+void wxLogTrace(wxTraceMask mask, const char* formatString, ... );
+void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr);
+//@}
+/** @ingroup group_funcmacro_log */
//@{
/**
- The right functions for debug output. They only do something in debug
- mode (when the preprocessor symbol __WXDEBUG__ is defined) and expand to
+ The right functions for debug output. They only do something in debug mode
+ (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to
nothing in release mode (otherwise).
+
+ @header{wx/log.h}
*/
void wxLogDebug(const char* formatString, ... );
void wxVLogDebug(const char* formatString, va_list argPtr);
//@}
-
+/** @ingroup group_funcmacro_log */
//@{
/**
- Messages logged by these functions will appear in the statusbar of the @a frame
- or of the top level application window by default (i.e. when using
+ Messages logged by this function will appear in the statusbar of the
+ @a frame or of the top level application window by default (i.e. when using
the second version of the functions).
+
If the target frame doesn't have a statusbar, the message will be lost.
+
+ @header{wx/log.h}
*/
-void wxLogStatus(wxFrame* frame, const char* formatString,
- ... );
-void wxVLogStatus(wxFrame* frame, const char* formatString,
- va_list argPtr);
+void wxLogStatus(wxFrame* frame, const char* formatString, ... );
+void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr);
void wxLogStatus(const char* formatString, ... );
void wxVLogStatus(const char* formatString, va_list argPtr);
//@}
-
+/** @ingroup group_funcmacro_log */
//@{
/**
- Mostly used by wxWidgets 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 (@e errno or @e ::GetLastError() depending
- on the platform) and the corresponding error message. The second form
- of this function takes the error code explicitly as the first argument.
+ Mostly used by wxWidgets 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 (@e errno or @e ::GetLastError()
+ depending on the platform) and the corresponding error message. The second
+ form of this function takes the error code explicitly as the first
+ argument.
@see wxSysErrorCode(), wxSysErrorMsg()
+
+ @header{wx/log.h}
*/
void wxLogSysError(const char* formatString, ... );
-void wxVLogSysError(const char* formatString,
- va_list argPtr);
+void wxVLogSysError(const char* formatString, va_list argPtr);
//@}
-
-/**
- Returns the error code from the last system call. This function uses
- @c errno on Unix platforms and @c GetLastError under Win32.
-
- @see wxSysErrorMsg(), wxLogSysError()
-*/
-unsigned long wxSysErrorCode();
-
-
-/**
- Returns the error message corresponding to the given system error code. If
- @a errCode is 0 (default), the last error code (as returned by
- wxSysErrorCode()) is used.
-
- @see wxSysErrorCode(), wxLogSysError()
-*/
-const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
-
-
+/** @ingroup group_funcmacro_log */
+//@{
+
+/**
+ @deprecated Replaced by wxLogDebug().
+
+ Displays a debugging message. Under Windows, this will appear on the
+ debugger command window, and under Unix, it will be written to standard
+ error.
+
+ The syntax is identical to @e printf(), pass a format string and a variable
+ list of arguments.
+
+ @note Under Windows, if your application crashes before the message appears
+ in the debugging window, put a wxYield() call after each wxDebugMsg()
+ call. wxDebugMsg() seems to be broken under WIN32s (at least for
+ Watcom C++): preformat your messages and use OutputDebugString
+ instead.
+
+ @header{wx/utils.h}
+*/
+void wxDebugMsg(const wxString& format, ... );
+
+/**
+ @deprecated Replaced by wxLogFatalError().
+
+ Displays @a message and exits. This writes to standard error under Unix,
+ and pops up a message box under Windows. Used for fatal internal wxWidgets
+ errors.
+
+ @eee wxError()
+
+ @header{wx/utils.h}
+*/
+void wxFatalError(const wxString& message,
+ const wxString& title = "wxWidgets Fatal Error");
+
+/**
+ @deprecated Replaced by wxLogError().
+
+ Displays @a message and continues. This writes to standard error under
+ Unix, and pops up a message box under Windows. Used for internal wxWidgets
+ errors.
+
+ @see wxFatalError()
+
+ @header{wx/utils.h}
+*/
+void wxError(const wxString& message,
+ const wxString& title = "wxWidgets Internal Error");
+
+//@}
+
+
+
/**
Returns the type of power source as one of @c wxPOWER_SOCKET,
@c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
bool wxGetUserId(char* buf, int sz);
//@}
-/**
- @b NB: This function is now obsolete, please use
- wxLogFatalError() instead.
- Displays @a msg and exits. This writes to standard error under Unix,
- and pops up a message box under Windows. Used for fatal internal
- wxWidgets errors. See also wxError().
-
- @header{wx/utils.h}
-*/
-void wxFatalError(const wxString& msg,
- const wxString& title = "wxWidgets Fatal Error");
-
/**
Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
@c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
*/
void wxRegisterId(long id);
-/**
- @b NB: This function is now obsolete, replaced by Log
- functions() and wxLogDebug() in particular.
- Display a debugging message; under Windows, this will appear on the
- debugger command window, and under Unix, it will be written to standard
- error.
- The syntax is identical to @b printf: pass a format string and a
- variable list of arguments.
- @b Tip: under Windows, if your application crashes before the
- message appears in the debugging window, put a wxYield call after
- each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
- (at least for Watcom C++): preformat your messages and use OutputDebugString
- instead.
-
- @header{wx/utils.h}
-*/
-void wxDebugMsg(const wxString& fmt, ... );
-
/**
For normal keys, returns @true if the specified key is currently down.
For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
wxString wxStripMenuCodes(const wxString& str,
int flags = wxStrip_All);
-/**
- @b NB: This function is now obsolete, please use wxLogError()
- instead.
- Displays @a msg and continues. This writes to standard error under
- Unix, and pops up a message box under Windows. Used for internal
- wxWidgets errors. See also wxFatalError().
-
- @header{wx/utils.h}
-*/
-void wxError(const wxString& msg,
- const wxString& title = "wxWidgets Internal Error");
-
/**
Open the @a url in user's default browser. If @a flags parameter contains
@c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
projects / wxWidgets.git / commitdiff
