clarified global and local config files behavior

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

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 1a99a1fb2097fdca7416505fbea782e40a6eae47..1e8528186b70c881531cfdf7cbd26cae865bef07 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -45,6 +45,7 @@ the corresponding topic.
 \helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\
 \helpref{wxCHECK\_MSG}{wxcheckmsg}\\
 \helpref{wxCHECK\_RET}{wxcheckret}\\
 \helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\
 \helpref{wxCHECK\_MSG}{wxcheckmsg}\\
 \helpref{wxCHECK\_RET}{wxcheckret}\\

+\helpref{wxCHECK\_SUNCC\_VERSION}{wxchecksunccversion}\\

 \helpref{wxCHECK\_VERSION}{wxcheckversion}\\
 \helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\
 \helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\
 \helpref{wxCHECK\_VERSION}{wxcheckversion}\\
 \helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\
 \helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\


@@ -69,6 +70,8 @@ the corresponding topic.
 \helpref{wxDROP\_ICON}{wxdropicon}\\
 \helpref{wxDebugMsg}{wxdebugmsg}\\
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{wxDROP\_ICON}{wxdropicon}\\
 \helpref{wxDebugMsg}{wxdebugmsg}\\
 \helpref{WXDEBUG\_NEW}{debugnew}\\

+\helpref{wxDEPRECATED}{wxdeprecated}\\
+\helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\

 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\
 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\


@@ -117,7 +120,6 @@ the corresponding topic.
 \helpref{wxGetDisplayName}{wxgetdisplayname}\\
 \helpref{wxGetDisplaySize}{wxdisplaysize}\\
 \helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\
 \helpref{wxGetDisplayName}{wxgetdisplayname}\\
 \helpref{wxGetDisplaySize}{wxdisplaysize}\\
 \helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\

-\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\

 \helpref{wxGetEmailAddress}{wxgetemailaddress}\\
 \helpref{wxGetEnv}{wxgetenv}\\
 \helpref{wxGetFileKind}{wxgetfilekind}\\
 \helpref{wxGetEmailAddress}{wxgetemailaddress}\\
 \helpref{wxGetEnv}{wxgetenv}\\
 \helpref{wxGetFileKind}{wxgetfilekind}\\


@@ -239,7 +241,6 @@ the corresponding topic.
 \helpref{wxSnprintf}{wxsnprintf}\\
 \helpref{wxSplit}{wxsplit}\\
 \helpref{wxSplitPath}{wxsplitfunction}\\
 \helpref{wxSnprintf}{wxsnprintf}\\
 \helpref{wxSplit}{wxsplit}\\
 \helpref{wxSplitPath}{wxsplitfunction}\\

-\helpref{wxStartTimer}{wxstarttimer}\\

 \helpref{wxStaticCast}{wxstaticcast}\\
 \helpref{wxStrcmp}{wxstrcmp}\\
 \helpref{wxStricmp}{wxstricmp}\\
 \helpref{wxStaticCast}{wxstaticcast}\\
 \helpref{wxStrcmp}{wxstrcmp}\\
 \helpref{wxStricmp}{wxstricmp}\\


@@ -317,6 +318,15 @@ compiler (g++) version major.minor or greater. Otherwise, and also if
 the compiler is not GNU C++ at all, returns $0$.
 
 
 the compiler is not GNU C++ at all, returns $0$.
 
 

+\membersection{wxCHECK\_SUNCC\_VERSION}\label{wxchecksunccversion}
+
+\func{bool}{wxCHECK\_SUNCC\_VERSION}{\param{}{major, minor}}
+
+Returns $1$ if the compiler being used to compile the code is Sun CC Pro
+compiler and its version is at least \texttt{major.minor}. Otherwise returns
+$0$.
+
+

 \membersection{wxCHECK\_VERSION}\label{wxcheckversion}
 
 \func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}}
 \membersection{wxCHECK\_VERSION}\label{wxcheckversion}
 
 \func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}}


@@ -350,7 +360,7 @@ Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that
 
 \membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion}
 
 
 \membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion}
 

-\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}}
+\func{bool}{wxCHECK\_W32API\_VERSION}{\param{}{major, minor, release}}

 
 Returns $1$ if the version of w32api headers used is major.minor.release or
 greater. Otherwise, and also if we are not compiling with mingw32/cygwin under
 
 Returns $1$ if the version of w32api headers used is major.minor.release or
 greater. Otherwise, and also if we are not compiling with mingw32/cygwin under


@@ -437,6 +447,15 @@ least the GUI part of) the library can't be used at all.
 Notice that parameters \arg{argc} and \arg{argv} may be modified by this
 function.
 
 Notice that parameters \arg{argc} and \arg{argv} may be modified by this
 function.
 

+An additional overload of wxEntryStart() is provided under MSW only: it is
+meant to be called with the parameters passed to \texttt{WinMain()}.
+
+\func{bool}{wxEntryStart}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}}
+
+(notice that under Windows CE platform, and only there, the type of 
+\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in
+Unicode build).
+

 \wxheading{Include files}
 
 <wx/init.h>
 \wxheading{Include files}
 
 <wx/init.h>


@@ -1037,7 +1056,7 @@ temporary storage that should not be deallocated.
 
 \membersection{::wxFindFirstFile}\label{wxfindfirstfile}
 
 
 \membersection{::wxFindFirstFile}\label{wxfindfirstfile}
 

-\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}
+\func{wxString}{wxFindFirstFile}{\param{const wxString\& }{spec}, \param{int}{ flags = 0}}

 
 This function does directory searching; returns the first file
 that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
 
 This function does directory searching; returns the first file
 that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to


@@ -1335,7 +1354,7 @@ Note that empty tokens will be generated if there are two or more adjacent separ
 
 \membersection{::wxSplitPath}\label{wxsplitfunction}
 
 
 \membersection{::wxSplitPath}\label{wxsplitfunction}
 

-\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
+\func{void}{wxSplitPath}{\param{const wxString\&}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}

 
 {\bf NB:} This function is obsolete, please use
 \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
 
 {\bf NB:} This function is obsolete, please use
 \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.


@@ -2851,6 +2870,36 @@ it is quoted automatically by the macro)}
 
 
 
 
 
 

+\membersection{wxDEPRECATED}\label{wxdeprecated}
+
+This macro can be used around a function declaration to generate warnings
+indicating that this function is deprecated (i.e. obsolete and planned to be
+removed in the future) when it is used. Only Visual C++ 7 and higher and g++
+compilers currently support this functionality.
+
+Example of use:
+\begin{verbatim}
+    // old function, use wxString version instead
+    wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
+
+    // ...
+    wxString wxGetSomething();
+\end{verbatim}
+
+
+\membersection{wxDEPRECATED\_BUT\_USED\_INTERNALLY}\label{wxdeprecatedbutusedinternally}
+
+This is a special version of \helpref{wxDEPRECATED}{wxdeprecated} macro which
+only does something when the deprecated function is used from the code outside
+wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.
+It is used with the virtual functions which are called by the library itself --
+even if such function is deprecated the library still has to call it to ensure
+that the existing code overriding it continues to work, but the use of this
+macro ensures that a deprecation warning will be generated if this function is
+used from the user code or, in case of Visual C++, even when it is simply
+overridden.
+
+

 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if


@@ -3252,7 +3301,10 @@ frame or dialog containing it, or {\tt NULL}.
 
 Open the \arg{url} in user's default browser. If \arg{flags} parameter contains
 \texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL
 
 Open the \arg{url} in user's default browser. If \arg{flags} parameter contains
 \texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL

-(currently this is only supported under Windows).
+(currently this is only supported under Windows). The \arg{url} may also be a
+local file path (with or without \texttt{file://} prefix), if it doesn't
+correspond to an existing file and the URL has no scheme \texttt{http://} is
+prepended to it by default.

 
 Returns \true if the application was successfully launched.
 
 
 Returns \true if the application was successfully launched.
 


@@ -4644,13 +4696,17 @@ Returns \true if the variable exists, \false otherwise.
 
 \membersection{wxSetEnv}\label{wxsetenv}
 
 
 \membersection{wxSetEnv}\label{wxsetenv}
 

-\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}}
+\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxString\& }{value}}

 
 Sets the value of the environment variable {\it var} (adding it if necessary)
 to {\it value}.
 
 Returns \true on success.
 
 
 Sets the value of the environment variable {\it var} (adding it if necessary)
 to {\it value}.
 
 Returns \true on success.
 

+\wxheading{See also}
+
+\helpref{wxUnsetEnv}{wxunsetenv}
+

 
 \membersection{wxUnsetEnv}\label{wxunsetenv}
 
 
 \membersection{wxUnsetEnv}\label{wxunsetenv}
 


@@ -4661,3 +4717,7 @@ Removes the variable {\it var} from the environment.
 function.
 
 Returns \true on success.
 function.
 
 Returns \true on success.

+
+\wxheading{See also}
+
+\helpref{wxSetEnv}{wxsetenv}