Defer retrieval of LANG env var, too. No memory management

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

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 1c17ad10741fa4758bbd420332f112cb7d75d360..ee1ed4a49894a2f07c42123f2c3f6d0c000eac71 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -67,10 +67,12 @@ For example:
 
 \membersection{::wxFindNextFile}\label{wxfindnextfile}
 
 
 \membersection{::wxFindNextFile}\label{wxfindnextfile}
 

-\func{wxString}{wxFindFirstFile}{\void}
+\func{wxString}{wxFindNextFile}{\void}

 
 Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
 
 
 Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
 

+See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
+

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


@@ -117,53 +119,6 @@ Copies {\it file1} to {\it file2}, returning TRUE if successful.
 
 Returns a string containing the current (or working) directory.
 
 
 Returns a string containing the current (or working) directory.
 

-\membersection{::wxGetHostName}\label{wxgethostname}
-
-\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}}
-
-Copies the current host machine's name into the supplied buffer.
-
-Under Windows or NT, this function first looks in the environment
-variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
-in the {\bf wxWindows} section of the WIN.INI file is tried.
-
-Returns TRUE if successful, FALSE otherwise.
-
-\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
-
-\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
-
-Copies the user's email address into the supplied buffer, by
-concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp
-and \helpref{wxGetUserId}{wxgetuserid}.
-
-Returns TRUE if successful, FALSE otherwise.
-
-\membersection{::wxGetUserId}\label{wxgetuserid}
-
-\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}}
-
-Copies the current user id into the supplied buffer.
-
-Under Windows or NT, this function first looks in the environment
-variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
-in the {\bf wxWindows} section of the WIN.INI file is tried.
-
-Returns TRUE if successful, FALSE otherwise.
-
-\membersection{::wxGetUserName}\label{wxgetusername}
-
-\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}}
-
-Copies the current user name into the supplied buffer.
-
-Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
-in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
-is running, the entry {\bf Current} in the section {\bf User} of
-the PENWIN.INI file is used.
-
-Returns TRUE if successful, FALSE otherwise.
-

 \membersection{::wxGetWorkingDirectory}
 
 \func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
 \membersection{::wxGetWorkingDirectory}
 
 \func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}


@@ -206,10 +161,13 @@ with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
 
 \membersection{::wxMkdir}
 
 
 \membersection{::wxMkdir}
 

-\func{bool}{wxMkdir}{\param{const wxString\& }{dir}}
+\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}

 
 Makes the directory {\it dir}, returning TRUE if successful.
 
 
 Makes the directory {\it dir}, returning TRUE if successful.
 

+{\it perm} is the access mask for the directory for the systems on which it is
+supported (Unix) and doesn't have effect for the other ones.
+

 \membersection{::wxRemoveFile}
 
 \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
 \membersection{::wxRemoveFile}
 
 \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}


@@ -276,6 +234,104 @@ use streams (within the document/view framework, for example).
 
 Use of this function requires the file wx\_doc.h to be included.
 
 
 Use of this function requires the file wx\_doc.h to be included.
 

+\section{Network functions}\label{networkfunctions}
+
+\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
+
+\func{wxString}{wxGetFullHostName}{\void}
+
+Returns the FQDN (fully qualified domain host name) or an empty string on
+error.
+
+See also: \helpref{wxGetHostName}{wxgethostname}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
+
+\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
+
+Copies the user's email address into the supplied buffer, by
+concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
+and \helpref{wxGetUserId}{wxgetuserid}.
+
+Returns TRUE if successful, FALSE otherwise.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxGetHostName}\label{wxgethostname}
+
+\func{wxString}{wxGetHostName}{\void}
+\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
+
+Copies the current host machine's name into the supplied buffer. Please note
+that the returned name is {\it not} fully qualified, i.e. it does not include
+the domain name.
+
+Under Windows or NT, this function first looks in the environment
+variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
+in the {\bf wxWindows} section of the WIN.INI file is tried.
+
+The first variant of this function returns the hostname if successful or an
+empty string otherwise. The second (deprecated) function returns TRUE
+if successful, FALSE otherwise.
+
+See also: \helpref{wxGetFullHostName}{wxgetfullhostname}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\section{User identification}\label{useridfunctions}
+
+\membersection{::wxGetUserId}\label{wxgetuserid}
+
+\func{wxString}{wxGetUserId}{\void}
+\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the "user id" also known as "login name" under Unix i.e.
+something like "jsmith". It uniquely identifies the current user (on this system).
+
+Under Windows or NT, this function first looks in the environment
+variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
+in the {\bf wxWindows} section of the WIN.INI file is tried.
+
+The first variant of this function returns the login name if successful or an
+empty string otherwise. The second (deprecated) function returns TRUE
+if successful, FALSE otherwise.
+
+See also: \helpref{wxGetUserName}{wxgetusername}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxGetUserName}\label{wxgetusername}
+
+\func{wxString}{wxGetUserName}{\void}
+\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the full user name (something like "Mr. John Smith").
+
+Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
+in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
+is running, the entry {\bf Current} in the section {\bf User} of
+the PENWIN.INI file is used.
+
+The first variant of this function returns the user name if successful or an
+empty string otherwise. The second (deprecated) function returns TRUE
+if successful, FALSE otherwise.
+
+See also: \helpref{wxGetUserId}{wxgetuserid}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+

 \section{String functions}
 
 \membersection{::copystring}
 \section{String functions}
 
 \membersection{::copystring}


@@ -377,7 +433,7 @@ Under Windows (only), the wildcard may be a specification for multiple
 types of file with a description for each, such as:
 
 \begin{verbatim}
 types of file with a description for each, such as:
 
 \begin{verbatim}

- "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif"
+ "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"

 \end{verbatim}
 
 The application must check for an empty return value (the user pressed
 \end{verbatim}
 
 The application must check for an empty return value (the user pressed


@@ -999,10 +1055,13 @@ arguments, terminated by NULL.
 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 sync} is FALSE (the default), flow of control immediately returns.
 If TRUE, the current application waits until the other program has terminated.
 

-In the case of synchronous execution, the return value is trhe exit code of
+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
 $-1$ if the process couldn't be started and typically 0 if the process
 the process (which terminates by the moment the function returns) and will be
 $-1$ if the process couldn't be started and typically 0 if the process

-terminated successfully.
+terminated successfully. Also, while waiting for the process to
+terminate, wxExecute will call \helpref{wxYield}{wxyield}. The caller
+should ensure that this can cause no recursion, in the simples case by 
+calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.

 
 For asynchronous execution, however, the return value is the process id and
 zero value indicates that the command could not be executed.
 
 For asynchronous execution, however, the return value is the process id and
 zero value indicates that the command could not be executed.


@@ -1319,6 +1378,33 @@ Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
 
 <wx/utils.h>
 
 
 <wx/utils.h>
 

+\membersection{::wxSafeYield}{wxsafeyield}
+
+\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
+
+This function is similar to wxYield, except that it disables the user input to
+all program windows before calling wxYield and re-enables it again
+afterwards. If {\it win} is not NULL, this window will remain enabled, 
+allowing the implementation of some limited user interaction.
+
+Returns the result of the call to \helpref{::wxYield}{wxyield}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxEnableTopLevelWindows}{wxenabletoplevelwindows}
+
+\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
+
+This function enables or disables all top level windows. It is used by
+\helpref{::wxSafeYield}{wxsafeyield}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+

 \membersection{::wxSetDisplayName}\label{wxsetdisplayname}
 
 \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
 \membersection{::wxSetDisplayName}\label{wxsetdisplayname}
 
 \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}


@@ -1489,7 +1575,8 @@ multitasking is cooperative) 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
 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.
+reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
+function.

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


@@ -2068,7 +2155,13 @@ assertion).
 
 \func{}{wxASSERT}{\param{}{condition}}
 
 
 \func{}{wxASSERT}{\param{}{condition}}
 

-Assert macro. An error message will be generated if the condition is FALSE.
+Assert macro. An error message will be generated if the condition is FALSE in
+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}

 
 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
 
 
 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
 


@@ -2076,18 +2169,28 @@ Assert macro. An error message will be generated if the condition is FALSE.
 
 Assert macro with message. An error message will be generated if the condition is FALSE.
 
 
 Assert macro with message. An error message will be generated if the condition is FALSE.
 

+See also: \helpref{wxASSERT}{wxassert}
+

 \membersection{wxFAIL}\label{wxfail}
 
 \membersection{wxFAIL}\label{wxfail}
 

-\func{}{wxFAIL}{\param{}{condition}}
+\func{}{wxFAIL}{\void}

 
 Will always generate an assert error if this code is reached (in debug mode).
 
 
 Will always generate an assert error if this code is reached (in debug mode).
 

+See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
+

 \membersection{wxFAIL\_MSG}\label{wxfailmsg}
 
 \membersection{wxFAIL\_MSG}\label{wxfailmsg}
 

-\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}}
+\func{}{wxFAIL\_MSG}{\param{}{msg}}

 
 Will always generate an assert error with specified message if this code is reached (in debug mode).
 
 
 Will always generate an assert error with specified message if this code is reached (in debug mode).
 

+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}
+

 \membersection{wxCHECK}\label{wxcheck}
 
 \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
 \membersection{wxCHECK}\label{wxcheck}
 
 \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}


@@ -2102,3 +2205,35 @@ This check is done even in release mode.
 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.
 
 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.
 

+This macro may be only used in non void functions, see also 
+\helpref{wxCHECK\_RET}{wxcheckret}.
+
+\membersection{wxCHECK\_RET}\label{wxcheckret}
+
+\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
+
+Checks that the condition is true, and returns if not (FAILs with given error
+message in debug mode). This check is done even in release mode.
+
+This macro should be used in void functions instead of 
+\helpref{wxCHECK\_MSG}{wxcheckmsg}.
+
+\membersection{wxCHECK2}\label{wxcheck2}
+
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
+
+Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute 
+{\it operation} if it is not. This is a generalisation of 
+\helpref{wxCHECK}{wxcheck} and may be used when something else than just
+returning from the function must be done when the {\it condition} is false.
+
+This check is done even in release mode.
+
+\membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
+
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
+
+This is the same as \helpref{wxCHECK2}{wxcheck2}, but 
+\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
+instead of wxFAIL() if the {\it condition} is false.
+