wxFont can now raelly use the native fonts

[wxWidgets.git] / docs / latex / wx / function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index d23f7160f2daeb15c98857213c5afe1de5a2545e..ee3b9474735ffe8c4f4ea1b06ef22f1f1996617a 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -11,7 +11,7 @@ The following constants are defined in wxWindows:
 \begin{itemize}\itemsep=0pt
 \item {\tt wxMAJOR\_VERSION} is the major version of wxWindows
 \item {\tt wxMINOR\_VERSION} is the minor version of wxWindows
 \begin{itemize}\itemsep=0pt
 \item {\tt wxMAJOR\_VERSION} is the major version of wxWindows
 \item {\tt wxMINOR\_VERSION} is the minor version of wxWindows

-\item {\tt wxRELASE\_NUMBER} is the release number
+\item {\tt wxRELEASE\_NUMBER} is the release number

 \end{itemize}
 
 For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and
 \end{itemize}
 
 For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and


@@ -177,6 +177,27 @@ Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{
 
 See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
 
 
 See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
 

+\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
+
+\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
+
+This function returns the total number of bytes and number of free bytes on
+the disk containing the directory {\it path} (it should exist). Both
+{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding
+information is not needed.
+
+\wxheading{Returns}
+
+{\tt TRUE} on success, {\tt FALSE} if an error occured (for example, the
+directory doesn't exist).
+
+\wxheading{Portability}
+
+This function is implemented for Win16 (only for drives less than 2Gb), Win32,
+Mac OS and generic Unix provided the system has {\tt statfs()} function.
+
+This function first appeared in wxWindows 2.3.2.
+

 \membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
 
 \func{wxString}{wxGetOSDirectory}{\void}
 \membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
 
 \func{wxString}{wxGetOSDirectory}{\void}


@@ -244,15 +265,19 @@ if the buffer is NULL.
 
 \func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
 
 
 \func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
 

-Makes a temporary filename based on {\it prefix}, opens and closes the file,
-and places the name in {\it buf}. If {\it buf} is NULL, new store
-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.
-
-It is the application's responsibility to create and delete the file.
+%% Makes a temporary filename based on {\it prefix}, opens and closes the file,
+%% and places the name in {\it buf}. If {\it buf} is NULL, new store
+%% 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.
+%%
+%% It is the application's responsibility to create and delete the file.
+
+These functions are obsolete, please use\rtfsp
+\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
+instead.

 
 \membersection{::wxIsWild}\label{wxiswild}
 
 
 \membersection{::wxIsWild}\label{wxiswild}
 


@@ -461,15 +486,34 @@ if successful, FALSE otherwise.
 Makes a copy of the string {\it s} using the C++ new operator, so it can be
 deleted with the {\it delete} operator.
 
 Makes a copy of the string {\it s} using the C++ new operator, so it can be
 deleted with the {\it delete} operator.
 

+\membersection{::wxIsEmpty}\label{wxisempty}
+
+\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
+
+Returns {\tt TRUE} if the pointer is either {\tt NULL} or points to an empty
+string, {\tt FALSE} otherwise.
+
+\membersection{::wxStricmp}\label{wxstricmp}
+
+\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+
+Returns a negative value, 0, or positive value if {\it p1} is less than, equal
+to or greater than {\it p2}. The comparison is case-insensitive.
+
+This function complements the standard C function {\it strcmp()} which performs
+case-sensitive comparison.
+

 \membersection{::wxStringMatch}
 
 \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
   \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
 
 \membersection{::wxStringMatch}
 
 \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
   \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
 

-Returns TRUE if the substring {\it s1} is found within {\it s2},
-ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
+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.
 
 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}}
 \membersection{::wxStringEq}\label{wxstringeq}
 
 \func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}


@@ -480,30 +524,15 @@ A macro defined as:
 #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
 \end{verbatim}
 
 #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
 \end{verbatim}
 

-\membersection{::IsEmpty}\label{isempty}
-
-\func{bool}{IsEmpty}{\param{const char *}{ p}}
+This function is obsolete, use \helpref{wxString}{wxstring} instead.

 
 

-Returns TRUE if the string is empty, FALSE otherwise. It is safe to pass NULL
-pointer to this function and it will return TRUE for it.
+\membersection{::wxStrlen}\label{wxstrlen}

 
 

-\membersection{::Stricmp}\label{stricmp}
-
-\func{int}{Stricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
-
-Returns a negative value, 0, or positive value if {\it p1} is less than, equal
-to or greater than {\it p2}. The comparison is case-insensitive.
-
-This function complements the standard C function {\it strcmp()} which performs
-case-sensitive comparison.
-
-\membersection{::Strlen}\label{strlen}
-
-\func{size\_t}{Strlen}{\param{const char *}{ p}}
+\func{size\_t}{wxStrlen}{\param{const char *}{ p}}

 
 This is a safe version of standard function {\it strlen()}: it does exactly the
 same thing (i.e. returns the length of the string) except that it returns 0 if
 
 This is a safe version of standard function {\it strlen()}: it does exactly the
 same thing (i.e. returns the length of the string) except that it returns 0 if

-{\it p} is the NULL pointer.
+{\it p} is the {\tt NULL} pointer.

 
 \membersection{::wxGetTranslation}\label{wxgettranslation}
 
 
 \membersection{::wxGetTranslation}\label{wxgettranslation}
 


@@ -572,6 +601,32 @@ is remembered between the 2 program runs.}
 
 <wx/tipdlg.h>
 
 
 <wx/tipdlg.h>
 

+\membersection{::wxDirSelector}\label{wxdirselector}
+
+\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
+ \param{const wxString\& }{default\_path = ""},\\
+ \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
+ \param{wxWindow *}{parent = NULL}}
+
+Pops up a directory selector dialog. The arguments have the same meaning as
+those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
+and the default\_path, if specified, is set as the initial selection.
+
+The application must check for an empty return value (if the user pressed
+Cancel). For example:
+
+\begin{verbatim}
+const wxString& dir = wxDirSelector("Choose a folder");
+if ( !dir.empty() )
+{
+  ...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/dirdlg.h>
+

 \membersection{::wxFileSelector}\label{wxfileselector}
 
 \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
 \membersection{::wxFileSelector}\label{wxfileselector}
 
 \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\


@@ -1647,7 +1702,7 @@ Gets operating system version information.
 
 \begin{twocollist}\itemsep=0pt
 \twocolitemruled{Platform}{Return types}
 
 \begin{twocollist}\itemsep=0pt
 \twocolitemruled{Platform}{Return types}

-\twocolitem{Macintosh}{Return value is wxMACINTOSH.}
+\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X.}

 \twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
 \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{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
 \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.}


@@ -1749,30 +1804,40 @@ normal way which usually just means that the application will be terminated.
 Calling wxHandleFatalExceptions() with {\it doIt} equal to FALSE will restore
 this default behaviour.
 
 Calling wxHandleFatalExceptions() with {\it doIt} equal to FALSE will restore
 this default behaviour.
 

-\membersection{::wxKill}\label{wxkill}
+\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
+
+\func{void}{wxInitAllImageHandlers}{\void}

 
 

-\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
+Initializes all available image handlers. For a list of available handlers,
+see \helpref{wxImage}{wximage}.

 
 

-Under Unix (the only supported platform), equivalent to the Unix kill function.
-Returns 0 on success, -1 on failure.
+\wxheading{See also}

 
 

-Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
-It does not raise a signal in the receiving process.
+\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}

 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 

-<wx/utils.h>
+<wx/image.h>

 
 

-\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
+\membersection{::wxInitialize}\label{wxinitialize}

 
 

-\func{void}{wxInitAllImageHandlers}{\void}
+\func{bool}{wxInitialize}{\void}

 
 

-Initializes all available image handlers. For a list of available handlers,
-see \helpref{wxImage}{wximage}.
+This function is used in wxBase only and only if you don't create
+\helpref{wxApp}{wxapp} object at all. In this case you must call it from your
+{\tt main()} function before calling any other wxWindows functions.

 
 

-\wxheading{See also}
+If the function returns {\tt FALSE} the initialization could not be performed,
+in this case the library cannot be used and
+\helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither.

 
 

-\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
+This function may be called several times but
+\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
+call to this function.
+
+\wxheading{Include files}
+
+<wx/app.h>

 
 \membersection{::wxIsBusy}\label{wxisbusy}
 
 
 \membersection{::wxIsBusy}\label{wxisbusy}
 


@@ -1787,6 +1852,63 @@ See also \helpref{wxBusyCursor}{wxbusycursor}.
 
 <wx/utils.h>
 
 
 <wx/utils.h>
 

+\membersection{::wxKill}\label{wxkill}
+
+\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
+
+\begin{verbatim}
+enum wxSignal
+{
+    wxSIGNONE = 0,  // verify if the process exists under Unix
+    wxSIGHUP,
+    wxSIGINT,
+    wxSIGQUIT,
+    wxSIGILL,
+    wxSIGTRAP,
+    wxSIGABRT,
+    wxSIGEMT,
+    wxSIGFPE,
+    wxSIGKILL,      // forcefully kill, dangerous!
+    wxSIGBUS,
+    wxSIGSEGV,
+    wxSIGSYS,
+    wxSIGPIPE,
+    wxSIGALRM,
+    wxSIGTERM       // terminate the process gently
+};
+\end{verbatim}
+
+{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
+under both Unix and Windows but all the other signals are equivalent to
+{\tt wxSIGTERM} under Windows.
+
+Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will
+be filled with an element of {\tt wxKillError} enum:
+
+\begin{verbatim}
+enum wxKillError
+{
+    wxKILL_OK,              // no error
+    wxKILL_BAD_SIGNAL,      // no such signal
+    wxKILL_ACCESS_DENIED,   // permission denied
+    wxKILL_NO_PROCESS,      // no such process
+    wxKILL_ERROR            // another, unspecified error
+};
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
+\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
+\helpref{Exec sample}{sampleexec}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+

 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
 
 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
 
 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}


@@ -1979,6 +2101,31 @@ This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}
 
 <wx/memory.h>
 
 
 <wx/memory.h>
 

+\membersection{::wxTrap}\label{wxtrap}
+
+\func{void}{wxTrap}{\void}
+
+In debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) this function generates a
+debugger exception meaning that the control is passed to the debugger if one is
+attached to the process. Otherwise the program just terminates abnormally.
+
+In release mode this function does nothing.
+
+\wxheading{Include files}
+
+<wx/debug.h>
+
+\membersection{::wxUninitialize}\label{wxuninitialize}
+
+\func{void}{wxUninitialize}{\void}
+
+This function is for use in console (wxBase) programs only. It must be called
+once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
+
+\wxheading{Include files}
+
+<wx/app.h>
+

 \membersection{::wxUsleep}\label{wxusleep}
 
 \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
 \membersection{::wxUsleep}\label{wxusleep}
 
 \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}


@@ -2026,22 +2173,10 @@ See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfig
 
 \func{bool}{wxYield}{\void}
 
 
 \func{bool}{wxYield}{\void}
 

-Yields control to pending messages in the windowing system. This can be useful, for example, when a
-time-consuming process writes to a text window. Without an occasional
-yield, the text window will not be updated properly, and on systems with
-cooperative multitasking, such as Windows 3.1 other processes will not respond.
-
-Caution should be exercised, however, since yielding may allow the
-user to perform actions which are not compatible with the current task.
-Disabling menu items or whole menus during processing can avoid unwanted
-reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
-function.
+Calls \helpref{wxApp::Yield}{wxappyield}.

 
 

-Note that wxYield will not flush the message logs. This is intentional as
-calling wxYield is usually done to quickly update the screen and popping up a
-message box dialog may be undesirable. If you do wish to flush the log
-messages immediately (otherwise it will be done during the next idle loop
-iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}.
+This function is kept only for backwards compatibility, please use the
+wxApp method instead in any new code.

 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 


@@ -2341,7 +2476,7 @@ avoid using {\tt \#ifdef}s when creating bitmaps.
 
 \membersection{wxConstCast}\label{wxconstcast}
 
 
 \membersection{wxConstCast}\label{wxconstcast}
 

-\func{}{wxConstCast}{ptr, classname}
+\func{classname *}{wxConstCast}{ptr, classname}

 
 This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler
 supports {\it const\_cast} or into an old, C-style cast, otherwise.
 
 This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler
 supports {\it const\_cast} or into an old, C-style cast, otherwise.


@@ -2370,14 +2505,15 @@ In non-debug mode, this is defined as the normal new operator.
 
 \membersection{wxDynamicCast}\label{wxdynamiccast}
 
 
 \membersection{wxDynamicCast}\label{wxdynamiccast}
 

-\func{}{wxDynamicCast}{ptr, classname}
+\func{classname *}{wxDynamicCast}{ptr, classname}

 
 This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
 
 This macro returns the pointer {\it ptr} cast to the type {\it classname *} if

-the pointer is of this type (the check is done during the run-time) or NULL
-otherwise. Usage of this macro is preferred over obsoleted wxObject::IsKindOf()
-function.
+the pointer is of this type (the check is done during the run-time) or
+{\tt NULL} otherwise. Usage of this macro is preferred over obsoleted
+wxObject::IsKindOf() function.

 
 

-The {\it ptr} argument may be NULL, in which case NULL will be returned.
+The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be
+returned.

 
 Example:
 
 
 Example:
 


@@ -2397,9 +2533,23 @@ Example:
 \wxheading{See also}
 
 \helpref{RTTI overview}{runtimeclassoverview}\\
 \wxheading{See also}
 
 \helpref{RTTI overview}{runtimeclassoverview}\\

+\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\

 \helpref{wxConstCast}{wxconstcast}\\
 \helpref{wxStatiicCast}{wxstaticcast}
 
 \helpref{wxConstCast}{wxconstcast}\\
 \helpref{wxStatiicCast}{wxstaticcast}
 

+\membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
+
+\func{classname *}{wxDynamicCastThis}{classname}
+
+This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
+latter provokes spurious compilation warnings from some compilers (because it
+tests whether {\tt this} pointer is non {\tt NULL} which is always true), so
+this macro should be used to avoid them.
+
+\wxheading{See also}
+
+\helpref{wxDynamicCast}{wxdynamiccast}
+

 \membersection{wxICON}\label{wxiconmacro}
 
 \func{}{wxICON}{iconName}
 \membersection{wxICON}\label{wxiconmacro}
 
 \func{}{wxICON}{iconName}


@@ -2419,7 +2569,7 @@ avoid using {\tt \#ifdef}s when creating icons.
 
 \membersection{wxStaticCast}\label{wxstaticcast}
 
 
 \membersection{wxStaticCast}\label{wxstaticcast}
 

-\func{}{wxStaticCast}{ptr, classname}
+\func{classname *}{wxStaticCast}{ptr, classname}

 
 This macro checks that the cast is valid in debug mode (an assert failure will
 result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
 
 This macro checks that the cast is valid in debug mode (an assert failure will
 result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the