X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f7bd26981f1c8d46d3909e3de90df081de4df33b..818e52c20151ce0c22aa752ccbab94f1ae7afc99:/docs/latex/wx/function.tex?ds=sidebyside

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 15c982dbe2..6062e1acb7 100644
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -18,7 +18,7 @@ Returns TRUE if the directory exists.
 
 \func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}}
 
-Converts a DOS to a UNIX filename by replacing backslashes with forward
+Converts a DOS to a Unix filename by replacing backslashes with forward
 slashes.
 
 \membersection{::wxFileExists}
@@ -84,7 +84,7 @@ pointer for long-term use.
 
 \func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
 
-Converts a UNIX to a DOS filename by replacing forward
+Converts a Unix to a DOS filename by replacing forward
 slashes with backslashes.
 
 \membersection{::wxConcatFiles}
@@ -168,7 +168,7 @@ is allocated for the temporary filename using {\it new}.
 
 Under Windows, the filename will include the drive and name of the
 directory allocated for temporary files (usually the contents of the
-TEMP variable). Under UNIX, the {\tt /tmp} directory is used.
+TEMP variable). Under Unix, the {\tt /tmp} directory is used.
 
 It is the application's responsibility to create and delete the file.
 
@@ -444,12 +444,12 @@ Returns TRUE if the display is colour, FALSE otherwise.
 
 Returns the depth of the display (a value of 1 denotes a monochrome display).
 
-\membersection{::wxMakeMetaFilePlaceable}\label{wxmakemetafileplaceable}
+\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
 
-\func{bool}{wxMakeMetaFilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
+\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
  \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
 
-Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetaFileDC}{wxmetafiledc})
+Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
 makes it into a placeable metafile by prepending a header containing the given
 bounding box. The bounding box may be obtained from a device context after drawing
 into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
@@ -676,7 +676,7 @@ Passes data to the clipboard.
 \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
 \item wxCF\_BITMAP: {\it data} is a wxBitmap.
 \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
-\item wxCF\_METAFILE: {\it data} is a wxMetaFile. {\it width} and {\it height} are used to give recommended dimensions.
+\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
 \end{itemize}
 
 The clipboard must have previously been opened for this call to succeed.
@@ -705,7 +705,7 @@ Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
 to its previous state. These two calls can be nested, and a counter
 ensures that only the outer calls take effect.
 
-See also \helpref{wxIsBusy}{wxisbusy}.
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
 
 \membersection{::wxBell}
 
@@ -729,12 +729,33 @@ if wxWindows does not get a chance to do it.
 Creates and returns an object of the given class, if the class has been
 registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
 
-\membersection{::wxDebugMsg}
+\membersection{::wxDDECleanUp}\label{wxddecleanup}
+
+\func{void}{wxDDECleanUp}{\void}
+
+Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
+called by the application.
+
+See also helpref{wxDDEInitialize}{wxddeinitialize}.
+
+\membersection{::wxDDEInitialize}\label{wxddeinitialize}
+
+\func{void}{wxDDEInitialize}{\void}
+
+Initializes the DDE system. May be called multiple times without harm.
+
+This no longer needs to be called by the application: it will be called
+by wxWindows if necessary.
+
+See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection}, 
+\helpref{wxDDECleanUp}{wxddecleanup}.
+
+\membersection{::wxDebugMsg}\label{wxdebugmsg}
 
 \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
 
 Display a debugging message; under Windows, this will appear on the
-debugger command window, and under UNIX, it will be written to standard
+debugger command window, and under Unix, it will be written to standard
 error.
 
 The syntax is identical to {\bf printf}: pass a format string and a
@@ -750,6 +771,8 @@ each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
 (at least for Watcom C++): preformat your messages and use OutputDebugString
 instead.
 
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
 \membersection{::wxDisplaySize}
 
 \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
@@ -777,14 +800,14 @@ wxWindows initialization under Windows (for applications constructed as a DLL).
 
 \func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
 
-wxWindows initialization under UNIX.
+wxWindows initialization under Unix.
 
 \membersection{::wxError}\label{wxerror}
 
 \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
 
 Displays {\it msg} and continues. This writes to standard error under
-UNIX, and pops up a message box under Windows. Used for internal
+Unix, and pops up a message box under Windows. Used for internal
 wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
 
 \membersection{::wxEndBusyCursor}\label{wxendbusycursor}
@@ -794,15 +817,15 @@ wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
 Changes the cursor back to the original cursor, for all windows in the application.
 Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
 
-See also \helpref{wxIsBusy}{wxisbusy}.
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
 
 \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\& *}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
 
-Executes another program in UNIX or Windows.
+Executes another program in Unix or Windows.
 
 The first form takes a command string, such as {\tt "emacs file.txt"}.
 
@@ -816,7 +839,7 @@ If execution is asynchronous, the return value is the process id,
 otherwise it is a status value.  A zero value indicates that the command could not
 be executed.
 
-If callback isn't NULL and if execution is asynchronous,
+If callback isn't NULL and if execution is asynchronous, 
 \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
 the process finishes.
 
@@ -835,7 +858,7 @@ application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \h
 
 \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
 
-Displays {\it msg} and exits. This writes to standard error under UNIX,
+Displays {\it msg} and exits. This writes to standard error under Unix,
 and pops up a message box under Windows. Used for fatal internal
 wxWindows errors. See also \helpref{wxError}{wxerror}.
 
@@ -881,7 +904,7 @@ Under X only, returns the current display name. See also \helpref{wxSetDisplayNa
 
 \func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}}
 
-Fills the buffer with a string representing the user's home directory (UNIX only).
+Fills the buffer with a string representing the user's home directory (Unix only).
 
 \membersection{::wxGetHostName}
 
@@ -889,7 +912,7 @@ Fills the buffer with a string representing the user's home directory (UNIX only
 
 Copies the host name of the machine the program is running on into the
 buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
-successful. Under UNIX, this will return a machine name. Under Windows,
+successful. Under Unix, this will return a machine name. Under Windows,
 this returns ``windows''.
 
 \membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
@@ -903,13 +926,13 @@ by this call.
 
 See also \helpref{wxTimer}{wxtimer}.
 
-\membersection{::wxGetFreeMemory}
+\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
 
 \func{long}{wxGetFreeMemory}{\void}
 
 Returns the amount of free memory in Kbytes under environments which
 support it, and -1 if not supported. Currently, returns a positive value
-under Windows, and -1 under UNIX.
+under Windows, and -1 under Unix.
 
 \membersection{::wxGetMousePosition}
 
@@ -926,6 +949,7 @@ Gets operating system version information.
 \begin{twocollist}\itemsep=0pt
 \twocolitemruled{Platform}{Return tyes}
 \twocolitem{Macintosh}{Return value is wxMACINTOSH.}
+\twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) }
 \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
 \twocolitem{OS/2}{Return value is wxOS2\_PM.}
 \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
@@ -953,7 +977,7 @@ Gets a resource value from the resource database (for example, WIN.INI, or
 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
 otherwise the specified file is used.
 
-Under X, if an application class (wxApp::wx\_class) has been defined,
+Under X, if an application class (wxApp::GetClassName) has been defined,
 it is appended to the string /usr/lib/X11/app-defaults/ to try to find
 an applications default file when merging all resource databases.
 
@@ -963,7 +987,7 @@ if the value exists in the resource file. It saves a separate
 test for that resource's existence, and it also allows
 the overloading of the function for different types.
 
-See also \helpref{wxWriteResource}{wxwriteresource}.
+See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
 
 \membersection{::wxGetUserId}
 
@@ -985,7 +1009,7 @@ Under Windows, this returns ``unknown''.
 
 \func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
 
-Under UNIX (the only supported platform), equivalent to the UNIX kill function.
+Under Unix (the only supported platform), equivalent to the Unix kill function.
 Returns 0 on success, -1 on failure.
 
 Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
@@ -998,23 +1022,6 @@ It does not raise a signal in the receiving process.
 Initializes the generic clipboard system by creating an instance of
 the class \helpref{wxClipboard}{wxclipboard}.
 
-\membersection{::wxIPCCleanUp}\label{wxipccleanup}
-
-\func{void}{wxIPCCleanUp}{\void}
-
-Call this when your application is terminating, if you have
-called \helpref{wxIPCInitialize}{wxipcinitialize}.
-
-\membersection{::wxIPCInitialize}\label{wxipcinitialize}
-
-\func{void}{wxIPCInitialize}{\void}
-
-Initializes for interprocess communication operation. May
-be called multiple times without harm.
-
-See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection}
-and the relevant section of the user manual.
-
 \membersection{::wxIsBusy}\label{wxisbusy}
 
 \func{bool}{wxIsBusy}{\void}
@@ -1022,6 +1029,8 @@ and the relevant section of the user manual.
 Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
 \helpref{wxEndBusyCursor}{wxendbusycursor} calls.
 
+See also \helpref{wxBusyCursor}{wxbusycursor}.
+
 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
 
 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
@@ -1080,18 +1089,22 @@ specified, then just the shell is spawned.
 
 See also \helpref{wxExecute}{wxexecute}.
 
-\membersection{::wxSleep}
+\membersection{::wxSleep}\label{wxsleep}
 
 \func{void}{wxSleep}{\param{int}{ secs}}
 
-Under X, sleeps for the specified number of seconds.
+Sleeps for the specified number of seconds.
 
 \membersection{::wxStripMenuCodes}
 
-\func{void}{wxStripMenuCodes}{\param{const wxString\& }{in}, \param{const wxString\& }{out}}
+\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
+
+\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
 
 Strips any menu codes from {\it in} and places the result
-in {\it out}. Menu codes include \& (mark the next character with an underline
+in {\it out} (or returns the new string, in the first form).
+
+Menu codes include \& (mark the next character with an underline
 as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
 
 \membersection{::wxStartTimer}\label{wxstarttimer}
@@ -1121,6 +1134,8 @@ Converts the character to upper case. This is implemented as a macro for efficie
 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}.
+
 \membersection{::wxTraceLevel}\label{wxtracelevel}
 
 \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
@@ -1131,6 +1146,8 @@ 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}.
+
 \membersection{::wxWriteResource}\label{wxwriteresource}
 
 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
@@ -1154,9 +1171,9 @@ Under X, the resource databases are cached until the internal function
 all updated resource databases are written to their files.
 
 Note that it is considered bad manners to write to the .Xdefaults
-file under UNIX, although the WIN.INI file is fair game under Windows.
+file under Unix, although the WIN.INI file is fair game under Windows.
 
-See also \helpref{wxGetResource}{wxgetresource}.
+See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
 
 \membersection{::wxYield}
 
@@ -1355,6 +1372,8 @@ base classes.
 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}.
+
 \membersection{WXTRACELEVEL}\label{tracelevel}
 
 \func{}{WXTRACELEVEL}{level, formatString, ...}
@@ -1365,6 +1384,8 @@ 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}.
+
 \section{wxWindows resource functions}\label{resourcefuncs}
 
 \overview{wxWindows resource system}{resourceformats}
@@ -1560,3 +1581,147 @@ is no connection between names used in resources, and the global bitmap data.
 
 Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
 
+\section{Log functions}\label{logfunctions}
+
+These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
+further information.
+
+\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.
+
+\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.
+
+\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.
+
+\membersection{wxFAIL}\label{wxfail}
+
+\func{}{wxFAIL}{\param{}{condition}}
+
+Will always generate an assert error if this code is reached (in debug mode).
+
+\membersection{wxFAIL\_MSG}\label{wxfailmsg}
+
+\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}}
+
+Will always generate an assert error with specified message if this code is reached (in debug mode).
+
+\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.
+
