X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7ac13b21fe95a726626ea554e9ba5a6d12bf3ce1..a84ece11fffdde5d1bbd254ba58ac3cee79c2e77:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 39342380ac..f3c4777e4b 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -9,6 +9,7 @@ the corresponding topic. \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}\\ @@ -23,7 +24,7 @@ the corresponding topic. \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}\\ @@ -36,9 +37,11 @@ the corresponding topic. \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}\\ @@ -48,12 +51,11 @@ the corresponding topic. \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}\\ @@ -68,7 +70,7 @@ the corresponding topic. \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}\\ @@ -89,6 +91,7 @@ the corresponding topic. \helpref{wxGetElapsedTime}{wxgetelapsedtime}\\ \helpref{wxGetEmailAddress}{wxgetemailaddress}\\ \helpref{wxGetEnv}{wxgetenv}\\ +\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\ \helpref{wxGetFreeMemory}{wxgetfreememory}\\ \helpref{wxGetFullHostName}{wxgetfullhostname}\\ \helpref{wxGetHomeDir}{wxgethomedir}\\ @@ -420,14 +423,22 @@ processes. \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"}. @@ -438,8 +449,9 @@ arguments, terminated by NULL. 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 @@ -457,10 +469,21 @@ 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 @@ -470,6 +493,20 @@ the messages from standard error output in the {\it errors} 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} @@ -481,7 +518,7 @@ See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, 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} @@ -623,7 +660,7 @@ threads. \helpref{wxFile}{wxfile}\\ \helpref{wxFileName}{wxfilename} -\membersection{::wxDirExists}\label{wxdirexists} +\membersection{::wxDirExists}\label{functionwxdirexists} \func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} @@ -636,7 +673,7 @@ Returns TRUE if the directory exists. 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}} @@ -1348,6 +1385,25 @@ is valid) if the dialog was cancelled. +\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} + + + + \membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices} \func{size\_t}{wxGetMultipleChoices}{\\ @@ -1903,7 +1959,7 @@ class instead. -\membersection{::wxClipboardOpen}\label{wxclipboardopen} +\membersection{::wxClipboardOpen}\label{functionwxclipboardopen} \func{bool}{wxClipboardOpen}{\void} @@ -2050,16 +2106,6 @@ See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, -\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} - - - \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows} \func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}} @@ -2231,21 +2277,11 @@ Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. \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} @@ -2316,7 +2352,7 @@ See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfig -\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 @@ -2374,7 +2410,7 @@ been compiled on a big-endian architecture, the value will be unchanged. 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 @@ -2954,39 +2990,39 @@ wxWindows errors. See also \helpref{wxError}{wxerror}. \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 @@ -2997,7 +3033,7 @@ meaningless. \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 @@ -3005,14 +3041,14 @@ progress (another, but possibly confusing name for the same function is {\bf wxL \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). @@ -3023,7 +3059,7 @@ If the target frame doesn't have a statusbar, the message will be lost. \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 @@ -3040,7 +3076,7 @@ of this function takes the error code explicitly as the first argument. \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 @@ -3049,15 +3085,16 @@ nothing in release mode (otherwise). \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 @@ -3299,9 +3336,14 @@ standard usleep() function is not MT safe. \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} @@ -3311,10 +3353,15 @@ builds. \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} @@ -3326,7 +3373,28 @@ 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} +\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} @@ -3334,7 +3402,43 @@ See also: \helpref{wxASSERT\_MSG}{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} @@ -3354,7 +3458,9 @@ 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} +\wxheading{See also} + +\helpref{wxFAIL}{wxfail} \membersection{wxCHECK}\label{wxcheck}