\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}
\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}
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.
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.
\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.
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}
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
(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}}
\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}
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"}.
\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}.
\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}
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}
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}
\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.}
.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.
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}
\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.
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}
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"}}
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}
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{...}{}}
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},
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}
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, ...}
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}
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.
+
projects / wxWidgets.git / blobdiff