\section{Alphabetical functions and macros list}
\helpref{CLASSINFO}{classinfo}\\
+\helpref{copystring}{copystring}\\
\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
\helpref{DECLARE\_APP}{declareapp}\\
\helpref{DECLARE\_CLASS}{declareclass}\\
\helpref{WXDEBUG\_NEW}{debugnew}\\
\helpref{WXTRACELEVEL}{tracelevel}\\
\helpref{WXTRACE}{trace}\\
-\helpref{copystring}{copystring}\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
\helpref{wxASSERT\_MSG}{wxassertmsg}\\
\helpref{wxASSERT}{wxassert}\\
\helpref{wxBITMAP}{wxbitmapmacro}\\
\helpref{wxCHECK\_VERSION}{wxcheckversion}\\
\helpref{wxCHECK}{wxcheck}\\
\helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
-\helpref{wxClipboardOpen}{wxclipboardopen}\\
+\helpref{wxClipboardOpen}{functionwxclipboardopen}\\
\helpref{wxCloseClipboard}{wxcloseclipboard}\\
\helpref{wxColourDisplay}{wxcolourdisplay}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\
\helpref{wxConcatFiles}{wxconcatfiles}\\
\helpref{wxConstCast}{wxconstcast}\\
\helpref{wxCopyFile}{wxcopyfile}\\
\helpref{wxDDEInitialize}{wxddeinitialize}\\
\helpref{wxDROP\_ICON}{wxdropicon}\\
\helpref{wxDebugMsg}{wxdebugmsg}\\
-\helpref{wxDirExists}{wxdirexists}\\
+\helpref{wxDirExists}{functionwxdirexists}\\
\helpref{wxDirSelector}{wxdirselector}\\
\helpref{wxDisplayDepth}{wxdisplaydepth}\\
-\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
-\helpref{wxDisplaySize}{wxdisplaysize}\\
\helpref{wxDisplaySize}{wxdisplaysize}\\
+\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
\helpref{wxDynamicCast}{wxdynamiccast}\\
\helpref{wxError}{wxerror}\\
\helpref{wxExecute}{wxexecute}\\
\helpref{wxExit}{wxexit}\\
+\helpref{wxEXPLICIT}{wxexplicit}\\
\helpref{wxFAIL\_MSG}{wxfailmsg}\\
\helpref{wxFAIL}{wxfail}\\
\helpref{wxFatalError}{wxfatalerror}\\
-\helpref{wxFileExists}{wxfileexists}\\
+\helpref{wxFileExists}{functionwxfileexists}\\
\helpref{wxFileModificationTime}{wxfilemodificationtime}\\
\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
\helpref{wxFileSelector}{wxfileselector}\\
\helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\
\helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\
\helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\
+\helpref{wxGetProcessId}{wxgetprocessid}\\
\helpref{wxGetResource}{wxgetresource}\\
\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\
\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\
\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
\helpref{wxGetTempFileName}{wxgettempfilename}\\
\helpref{wxGetTextFromUser}{wxgettextfromuser}\\
+\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\
\helpref{wxGetTranslation}{wxgettranslation}\\
\helpref{wxGetUTCTime}{wxgetutctime}\\
\helpref{wxGetUserHome}{wxgetuserhome}\\
\helpref{wxResourceRegisterBitmapData}{registerbitmapdata}\\
\helpref{wxResourceRegisterIconData}{wxresourceregistericondata}\\
\helpref{wxRmdir}{wxrmdir}\\
+\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\
\helpref{wxSafeYield}{wxsafeyield}\\
\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
\helpref{wxSetCursor}{wxsetcursor}\\
\helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
\helpref{wxShell}{wxshell}\\
\helpref{wxShowTip}{wxshowtip}\\
+\helpref{wxShutdown}{wxshutdown}\\
\helpref{wxSleep}{wxsleep}\\
\helpref{wxSnprintf}{wxsnprintf}\\
\helpref{wxSplitPath}{wxsplitfunction}\\
\membersection{::wxExecute}\label{wxexecute}
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
-\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
+an array reference.}
+
\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 3-element list {\tt ( status, output, errors )}, where
+{\tt output} and {\tt errors} are array references.}
+
Executes another program in Unix or Windows.
The first form takes a command string, such as {\tt "emacs file.txt"}.
The semantics of the third and fourth versions is different from the first two
and is described in more details below.
-If {\it sync} is FALSE (the default), flow of control immediately returns.
-If TRUE, the current application waits until the other program has terminated.
+If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
+of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
+application waits until the other program has terminated.
In the case of synchronous execution, the return value is the exit code of
the process (which terminates by the moment the function returns) and will be
For asynchronous execution, however, the return value is the process id and
zero value indicates that the command could not be executed. As an added
-complication, the return value of $-1$ in this case indicattes that we didn't
+complication, the return value of $-1$ in this case indicates that we didn't
launch a new process, but connected to the running one (this can only happen in
case of using DDE under Windows for command execution). In particular, in this,
and only this, case the calling code will not get the notification about
process termination.
-If callback isn't NULL and if execution is asynchronous (note that callback
-parameter can not be non-NULL for synchronous execution),
+If callback isn't NULL and if execution is asynchronous,
\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
-the process finishes.
+the process finishes. Specifying this parameter also allows you to redirect the
+standard input and/or output of the process being launched by calling
+\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
+under Windows the process window is not shown by default (this avoids having to
+flush an unnecessary console for the processes which don't create any windows
+anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
+happening, i.e. with this flag the child process window will be shown normally.
+
+Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
+that the new process is a group leader (this will create a new session if
+needed). Calling \helpref{wxKill}{wxkill} with the argument of -pid where pid
+is the process ID of the new process will kill this process as well as all of
+its children (except those which have started their own session).
Finally, you may use the third overloaded version of this function to execute
a process (always synchronously) and capture its output in the array
See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
\helpref{Exec sample}{sampleexec}.
+\wxheading{Parameters}
+
+\docparam{command}{The command to execute and any parameters to pass to it as a
+single string.}
+
+\docparam{argv}{The command to execute should be the first element of this
+array, any additional ones are the command parameters and the array must be
+terminated with a NULL pointer.}
+
+\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},
+{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
+
+\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
+
\wxheading{Include files}
<wx/utils.h>
Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
Should only be used in an emergency: normally the top-level frame
should be deleted (after deleting all other frames) to terminate the
-application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
+application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.
\wxheading{Include files}
\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}}
Equivalent to the Unix kill function: send the given signal {\it sig} to the
-process with PID {\it pid}. The valud signal values are
+process with PID {\it pid}. The valid signal values are
\begin{verbatim}
enum wxSignal
<wx/utils.h>
+\membersection{::wxGetProcessId}\label{wxgetprocessid}
+
+\func{unsigned long}{wxGetProcessId}{\void}
+
+Returns the number uniquely identifying the current process in the system.
+
+If an error occurs, $0$ is returned.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
\membersection{::wxShell}\label{wxshell}
\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
<wx/utils.h>
+\membersection{::wxShutdown}\label{wxshutdown}
+
+\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}}
+
+This function shuts down or reboots the computer depending on the value of the
+{\it flags}. Please notice that doing this requires the corresponding access
+rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT)
+and that this function is only implemented under Unix and Win32.
+
+\wxheading{Parameters}
+
+\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}}
+
+\wxheading{Returns}
+
+{\tt TRUE} on success, {\tt FALSE} if an error occured.
+
+\wxheading{Include files}
+
+<wx/utils.h>
\section{Thread functions}\label{threadfunctions}
\helpref{wxFile}{wxfile}\\
\helpref{wxFileName}{wxfilename}
-\membersection{::wxDirExists}\label{wxdirexists}
+\membersection{::wxDirExists}\label{functionwxdirexists}
\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
Converts a DOS to a Unix filename by replacing backslashes with forward
slashes.
-\membersection{::wxFileExists}\label{wxfileexists}
+\membersection{::wxFileExists}\label{functionwxfileexists}
\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
\func{char *}{wxFileNameFromPath}{\param{char *}{path}}
+{\bf NB:} This function is obsolete, please use
+\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
+
Returns the filename for a full path. The second form returns a pointer to
temporary storage that should not be deallocated.
Copies {\it file1} to {\it file2}, returning TRUE if successful. If
{\it overwrite} parameter is TRUE (default), the destination file is overwritten
-if it exists, but if {\it overwrite} is FALSE, the functions failes in this
+if it exists, but if {\it overwrite} is FALSE, the functions fails in this
case.
\membersection{::wxGetCwd}\label{wxgetcwd}
\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
-This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
+{\bf NB:} This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
Copies the current working directory into the buffer if supplied, or
copies the working directory into new storage (which you must delete yourself)
%%
%% It is the application's responsibility to create and delete the file.
-These functions are obsolete, please use\rtfsp
+{\bf NB:} These functions are obsolete, please use\rtfsp
\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
instead.
\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
+{\bf NB:} This function is obsolete, please use
+\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
+
This function splits a full file name into components: the path (including possible disk/drive
specification under Windows), the base name and the extension. Any of the output parameters
({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
\param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
+{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
+
Returns {\tt TRUE} if the substring {\it s1} is found within {\it s2},
ignoring case if {\it exact} is FALSE. If {\it subString} is {\tt FALSE},
no substring matching is done.
-This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
-
\membersection{::wxStringEq}\label{wxstringeq}
\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
+
A macro defined as:
\begin{verbatim}
#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
\end{verbatim}
-This function is obsolete, use \helpref{wxString}{wxstring} instead.
-
\membersection{::wxStrlen}\label{wxstrlen}
\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
Cancel). For example:
\begin{verbatim}
-const wxString& s = wxFileSelector("Choose a file to open");
-if (s)
+wxString filename = wxFileSelector("Choose a file to open");
+if ( !filename.empty() )
{
- ...
+ // work with the file
+ ...
}
+//else: cancelled by user
\end{verbatim}
\wxheading{Include files}
\section{Printer settings}\label{printersettings}
-These routines are obsolete and should no longer be used!
+{\bf NB:} These routines are obsolete and should no longer be used!
The following functions are used to control PostScript printing. Under
Windows, PostScript output can only be sent to a file.
<wx/clipbrd.h>
-\membersection{::wxClipboardOpen}\label{wxclipboardopen}
+\membersection{::wxClipboardOpen}\label{functionwxclipboardopen}
\func{bool}{wxClipboardOpen}{\void}
\section{Miscellaneous functions}\label{miscellany}
+\membersection{wxEXPLICIT}\label{wxexplicit}
+
+{\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
+the compiler supports it or nothing otherwise. Thus, it can be used even in the
+code which might have to be compiled with an old compiler without support for
+this language feature but still take advantage of it when it is available.
+
\membersection{::wxNewId}\label{wxnewid}
\func{long}{wxNewId}{\void}
<wx/dde.h>
-\membersection{::wxDisplaySize}\label{wxdisplaysize}
-
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
-
-Gets the physical size of the display in pixels.
-
-\wxheading{Include files}
-
-<wx/gdicmn.h>
-
\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
+{\bf NB:} This function is obsolete, please use
+\helpref{wxWindow::FindWindowByLabel}{wxwindowfindwindowbylabel} instead.
+
Find a window by its label. Depending on the type of window, the label may be a window title
or panel item label. If {\it parent} is NULL, the search will start from all top-level
frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
+{\bf NB:} This function is obsolete, please use
+\helpref{wxWindow::FindWindowByName}{wxwindowfindwindowbyname} instead.
+
Find a window by its name (as given in a window constructor or {\bf Create} function call).
If {\it parent} is NULL, the search will start from all top-level
frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
<wx/utils.h>
+\membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
+
+\func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
+
+Returns the first top level parent of the given window, or in other words, the
+frame or dialog containing it, or {\tt NULL}.
+
+\wxheading{Include files}
+
+<wx/window.h>
+
\membersection{::wxLoadUserResource}\label{wxloaduserresource}
\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
\func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
-This function posts the event to the specified {\it dest} object. The
-difference between sending an event and posting it is that in the first case
-the event is processed before the function returns (in wxWindows, event sending
-is done with \helpref{ProcessEvent}{wxevthandlerprocessevent} function), but in
-the second, the function returns immediately and the event will be processed
-sometime later - usually during the next even loop iteration.
-
-Note that a copy of the {\it event} is made by the function, so the original
-copy can be deleted as soon as function returns. This function can also be used
-to send events between different threads safely. As this function makes a
-copy of the event, the event needs to have a fully implemented Clone() method,
-which may not be the case for all event in wxWindows.
-
-See also \helpref{AddPendingEvent}{wxevthandleraddpendingevent} (which this function
-uses internally).
+In a GUI application, this function posts {\it event} to the specified {\it dest}
+object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
+Otherwise, it dispatches {\it event} immediately using
+\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}.
+See the respective documentation for details (and caveats).
\wxheading{Include files}
\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}
-This function is obsolete, please use
+{\bf NB:} This function is obsolete, please use
\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead.
Strips any menu codes from {\it in} and places the result
<wx/utils.h>
-\section{Byte order macros}\label{macros}
+\section{Byte order macros}\label{byteordermacros}
The endian-ness issues (that is the difference between big-endian and
little-endian architectures) are important for the portable programs working
Use these macros to read data from and write data to a file that stores
data in big-endian format.
-\section{RTTI functions}\label{macros}
+\section{RTTI functions}\label{rttimacros}
wxWindows uses its own RTTI ("run-time type identification") system which
predates the current standard C++ RTTI and so is kept for backwards
-compatribility reasons but also because it allows some things which the
+compatibility reasons but also because it allows some things which the
standard RTTI doesn't directly support (such as creating a class from its
name).
\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
-\tt{#}defining a name to an integer). Unlikely to be used by an application except
+{\tt\#}defining a name to an integer). Unlikely to be used by an application except
perhaps for implementing resource functionality for interpreted languages.
\membersection{::wxResourceClear}\label{wxresourceclear}
\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char **}{xpm\_data}}
-Makes \tt{#}included XBM or XPM bitmap data known to the wxWindows resource system.
+Makes {\tt\#}included XBM or XPM bitmap data known to the wxWindows resource system.
This is required if other resources will use the bitmap data, since otherwise there
is no connection between names used in resources, and the global bitmap data.
\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
-{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log
+functions}{logfunctions} and \helpref{wxLogDebug}{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
(at least for Watcom C++): preformat your messages and use OutputDebugString
instead.
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
\wxheading{Include files}
<wx/utils.h>
\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
-This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
+{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
instead.
Displays {\it msg} and continues. This writes to standard error under
\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
-This function is now obsolete, please use
+{\bf NB:} This function is now obsolete, please use
\helpref{wxLogFatalError}{wxlogfatalerror} instead.
Displays {\it msg} and exits. This writes to standard error under Unix,
\item wxTraceOleCalls: trace OLE method calls (Win32 only)
\end{itemize}
+\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
+
+\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
+
+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
+\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
+it simply prints the message to the standard output using the title as prefix.
+
+\wxheading{Parameters}
+
+\docparam{title}{The title of the message box shown to the user or the prefix
+of the message string}
+
+\docparam{text}{The text to show to the user}
+
+\wxheading{See also}
+
+\helpref{wxLogFatalError}{wxlogfatalerror}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
\membersection{::wxSysErrorCode}\label{wxsyserrorcode}
\func{unsigned long}{wxSysErrorCode}{\void}
\func{}{WXTRACE}{formatString, ...}
+{\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
Calls wxTrace with printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
\wxheading{Include files}
<wx/memory.h>
\func{}{WXTRACELEVEL}{level, formatString, ...}
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
Calls wxTraceLevel with printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
The first argument should be the level at which this information is appropriate.
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
this value.
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
\wxheading{Include files}
<wx/memory.h>
\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
Takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
\wxheading{Include files}
<wx/memory.h>
\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
Takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
The first argument should be the level at which this information is appropriate.
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
this value.
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
\wxheading{Include files}
<wx/memory.h>
\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
-\func{wxLongLone}{wxGetLocalTimeMillis}{\void}
+\func{wxLongLong}{wxGetLocalTimeMillis}{\void}
Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
\wxheading{See also}
\helpref{wxDateTime::Now}{wxdatetimenow},\\
-\helpref{wxLongLone}{wxlonglong}
+\helpref{wxLongLong}{wxlonglong}
\wxheading{Include files}
\section{Debugging macros and functions}\label{debugmacros}
-Useful macros and functions for error checking and defensive programming. ASSERTs are only
-compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
-builds.
+Useful macros and functions for error checking and defensive programming.
+wxWindows defines three families of the assert-like macros:
+the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
+(in other words, in the debug build) but disappear completely in the release
+build. On the other hand, the wxCHECK macros stay event in release builds but a
+check failure doesn't generate any user-visible effects then. Finally, the
+compile time assertions don't happen during the run-time but result in the
+compilation error messages if the condition they check fail.
\wxheading{Include files}
\membersection{::wxOnAssert}\label{wxonassert}
-\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{msg = NULL}}
+\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{cond}, \param{const char *}{msg = NULL}}
+
+This function is called whenever one of debugging macros fails (i.e. condition
+is false in an assertion). It is only defined in the debug mode, in release
+builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
-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.
+To override the default behaviour in the debug builds which is to show the user
+a dialog asking whether he wants to abort the program, continue or continue
+ignoring any subsequent assert failures, you may override
+\helpref{wxApp::OnAssert}{wxapponassert} which is called by this function if
+the global application object exists.
\membersection{wxASSERT}\label{wxassert}
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}
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
+
+\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
+
+\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
+
+This macro results in a
+\helpref{compile time assertion failure}{wxcompiletimeassert} if the size
+of the given type {\it type} is less than {\it size} bits.
+
+You may use it like this, for example:
+
+\begin{verbatim}
+ // we rely on the int being able to hold values up to 2^32
+ wxASSERT_MIN_BITSIZE(int, 32);
+
+ // can't work with the platforms using UTF-8 for wchar_t
+ wxASSERT_MIN_BITSIZE(wchar_t, 16);
+\end{verbatim}
\membersection{wxASSERT\_MSG}\label{wxassertmsg}
Assert macro with message. An error message will be generated if the condition is FALSE.
-See also: \helpref{wxASSERT}{wxassert}
+\wxheading{See also}
+
+\helpref{wxASSERT}{wxassert},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
+
+\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
+
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
+
+Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
+specified {\it condition} is false. The compiler error message should include
+the {\it msg} identifier - please note that it must be a valid C++ identifier
+and not a string unlike in the other cases.
+
+This macro is mostly useful for testing the expressions involving the
+{\tt sizeof} operator as they can't be tested by the preprocessor but it is
+sometimes desirable to test them at the compile time.
+
+Note that this macro internally declares a struct whose name it tries to make
+unique by using the {\tt \_\_LINE\_\_} in it but it may still not work if you
+use it on the same line in two different source files. In this case you may
+either change the line in which either of them appears on or use the
+\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro.
+
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
+
+\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2}
+
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}}
+
+This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}
+except that it allows you to specify a unique {\it name} for the struct
+internally defined by this macro to avoid getting the compilation errors
+described \helpref{above}{wxcompiletimeassert}.
\membersection{wxFAIL}\label{wxfail}
it may be used in the "default:" branch of a switch statement if all possible
cases are processed above.
-See also: \helpref{wxFAIL}{wxfail}
+\wxheading{See also}
+
+\helpref{wxFAIL}{wxfail}
\membersection{wxCHECK}\label{wxcheck}
projects / wxWidgets.git / blobdiff