\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{wxClipboardOpen}{wxclipboardopen}\\
\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{wxGetElapsedTime}{wxgetelapsedtime}\\
\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
\helpref{wxGetEnv}{wxgetenv}\\
+\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
\helpref{wxGetFreeMemory}{wxgetfreememory}\\
\helpref{wxGetFullHostName}{wxgetfullhostname}\\
\helpref{wxGetHomeDir}{wxgethomedir}\\
\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"}.
<wx/colordlg.h>
+\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
+
+\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}}
+
+Shows the font selection dialog and returns the font selected by user or
+invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font
+is valid) if the dialog was cancelled.
+
+\wxheading{Parameters}
+
+\docparam{parent}{The parent window for the font selection dialog}
+
+\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
+
+\wxheading{Include files}
+
+<wx/fontdlg.h>
+
+
\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
\func{size\_t}{wxGetMultipleChoices}{\\
\membersection{::wxLogError}\label{wxlogerror}
-\func{void}{wxLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-
\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
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.
\membersection{::wxLogFatalError}\label{wxlogfatalerror}
-\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-
\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
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{va\_list }{argPtr}}
-
\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
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{va\_list }{argPtr}}
-
\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
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
\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
For verbose output. Normally, it is suppressed, but
might be activated if the user wishes to know more details about the program
\membersection{::wxLogStatus}\label{wxlogstatus}
-\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
-
\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
Messages logged by these functions will appear in the statusbar of the {\it
frame} or of the top level application window by default (i.e. when using
the second version of the functions).
\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
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
\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
The right functions for debug output. They only do something in debug
mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to
\membersection{::wxLogTrace}\label{wxlogtrace}
\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
-\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
As {\bf wxLogDebug}, trace functions only do something in debug build and
expand to nothing in the release one. The reason for making
\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}
\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.
+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.
+
+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 involing 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