1. reset default item in ~wxWindow (better to be safe)

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

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index b85ec925e5674b0cfe3e08f5eb690501a91f1ebe..aab0d2bcb6121dccde6c6ec05a0ec15026482a26 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -461,15 +461,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 +499,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}}
-
-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{::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.
+This function is obsolete, use \helpref{wxString}{wxstring} instead.

 
 

-\membersection{::Strlen}\label{strlen}
+\membersection{::wxStrlen}\label{wxstrlen}

 
 

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


@@ -1466,7 +1470,12 @@ should ensure that this can cause no recursion, in the simplest case by
 calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.
 
 For asynchronous execution, however, the return value is the process id and
 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.
+zero value indicates that the command could not be executed. As an added
+complication, the return value of $-1$ in this case indicattes that we didn't
+launch a new process, but connected to the running one (this can only happen in
+case of using DDE under Windows for command execution). In particular, in this,
+and only this, case the calling code will not get the notification about
+process termination.

 
 If callback isn't NULL and if execution is asynchronous (note that callback
 parameter can not be non-NULL for synchronous execution),
 
 If callback isn't NULL and if execution is asynchronous (note that callback
 parameter can not be non-NULL for synchronous execution),


@@ -1744,30 +1753,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{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
+\func{void}{wxInitAllImageHandlers}{\void}

 
 

-Under Unix (the only supported platform), equivalent to the Unix kill function.
-Returns 0 on success, -1 on failure.
+Initializes all available image handlers. For a list of available handlers,
+see \helpref{wxImage}{wximage}.

 
 

-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.
+\wxheading{See also}
+
+\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}
 


@@ -1782,6 +1801,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"}}


@@ -1974,6 +2050,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}}


@@ -2336,7 +2437,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.


@@ -2365,14 +2466,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:
 


@@ -2392,9 +2494,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}


@@ -2414,7 +2530,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


@@ -2477,7 +2593,7 @@ loading from resource data.
 \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
 
 Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
 \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
 
 Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp

-\verb$#$defining a name to an integer). Unlikely to be used by an application except
+\tt{#}defining a name to an integer). Unlikely to be used by an application except

 perhaps for implementing resource functionality for interpreted languages.
 
 \membersection{::wxResourceClear}
 perhaps for implementing resource functionality for interpreted languages.
 
 \membersection{::wxResourceClear}


@@ -2643,7 +2759,7 @@ load an entire {\tt .wxr file} into a string.
 
 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char** }{xpm\_data}}
 
 
 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char** }{xpm\_data}}
 

-Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
+Makes \tt{#}included XBM or XPM bitmap data known to the wxWindows resource system.

 This is required if other resources will use the bitmap data, since otherwise there
 is no connection between names used in resources, and the global bitmap data.
 
 This is required if other resources will use the bitmap data, since otherwise there
 is no connection between names used in resources, and the global bitmap data.