removed Left(char ch) version which doesn't exist any more

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

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 35eeebcb3ee44e066b672640d1583391008afef1..2568e53be0d7cbb9e43e3a798d3134d73f5eef8d 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -37,7 +37,7 @@ the corresponding topic.
 \helpref{wxCHECK\_VERSION}{wxcheckversion}\\
 \helpref{wxCHECK}{wxcheck}\\
 \helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
 \helpref{wxCHECK\_VERSION}{wxcheckversion}\\
 \helpref{wxCHECK}{wxcheck}\\
 \helpref{wxClientDisplayRect}{wxclientdisplayrect}\\

-\helpref{wxClipboardOpen}{wxclipboardopen}\\
+\helpref{wxClipboardOpen}{functionwxclipboardopen}\\

 \helpref{wxCloseClipboard}{wxcloseclipboard}\\
 \helpref{wxColourDisplay}{wxcolourdisplay}\\
 \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
 \helpref{wxCloseClipboard}{wxcloseclipboard}\\
 \helpref{wxColourDisplay}{wxcolourdisplay}\\
 \helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\


@@ -51,12 +51,11 @@ the corresponding topic.
 \helpref{wxDDEInitialize}{wxddeinitialize}\\
 \helpref{wxDROP\_ICON}{wxdropicon}\\
 \helpref{wxDebugMsg}{wxdebugmsg}\\
 \helpref{wxDDEInitialize}{wxddeinitialize}\\
 \helpref{wxDROP\_ICON}{wxdropicon}\\
 \helpref{wxDebugMsg}{wxdebugmsg}\\

-\helpref{wxDirExists}{wxdirexists}\\
+\helpref{wxDirExists}{functionwxdirexists}\\

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

-\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
-\helpref{wxDisplaySize}{wxdisplaysize}\\

 \helpref{wxDisplaySize}{wxdisplaysize}\\
 \helpref{wxDisplaySize}{wxdisplaysize}\\

+\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\

 \helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
 \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
 \helpref{wxDynamicCast}{wxdynamiccast}\\
 \helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
 \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
 \helpref{wxDynamicCast}{wxdynamiccast}\\


@@ -71,7 +70,7 @@ the corresponding topic.
 \helpref{wxFAIL\_MSG}{wxfailmsg}\\
 \helpref{wxFAIL}{wxfail}\\
 \helpref{wxFatalError}{wxfatalerror}\\
 \helpref{wxFAIL\_MSG}{wxfailmsg}\\
 \helpref{wxFAIL}{wxfail}\\
 \helpref{wxFatalError}{wxfatalerror}\\

-\helpref{wxFileExists}{wxfileexists}\\
+\helpref{wxFileExists}{functionwxfileexists}\\

 \helpref{wxFileModificationTime}{wxfilemodificationtime}\\
 \helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
 \helpref{wxFileSelector}{wxfileselector}\\
 \helpref{wxFileModificationTime}{wxfilemodificationtime}\\
 \helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
 \helpref{wxFileSelector}{wxfileselector}\\


@@ -121,6 +120,7 @@ the corresponding topic.
 \helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
 \helpref{wxGetTempFileName}{wxgettempfilename}\\
 \helpref{wxGetTextFromUser}{wxgettextfromuser}\\
 \helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
 \helpref{wxGetTempFileName}{wxgettempfilename}\\
 \helpref{wxGetTextFromUser}{wxgettextfromuser}\\

+\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\

 \helpref{wxGetTranslation}{wxgettranslation}\\
 \helpref{wxGetUTCTime}{wxgetutctime}\\
 \helpref{wxGetUserHome}{wxgetuserhome}\\
 \helpref{wxGetTranslation}{wxgettranslation}\\
 \helpref{wxGetUTCTime}{wxgetutctime}\\
 \helpref{wxGetUserHome}{wxgetuserhome}\\


@@ -196,6 +196,7 @@ the corresponding topic.
 \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
 \helpref{wxShell}{wxshell}\\
 \helpref{wxShowTip}{wxshowtip}\\
 \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
 \helpref{wxShell}{wxshell}\\
 \helpref{wxShowTip}{wxshowtip}\\

+\helpref{wxShutdown}{wxshutdown}\\

 \helpref{wxSleep}{wxsleep}\\
 \helpref{wxSnprintf}{wxsnprintf}\\
 \helpref{wxSplitPath}{wxsplitfunction}\\
 \helpref{wxSleep}{wxsleep}\\
 \helpref{wxSnprintf}{wxsnprintf}\\
 \helpref{wxSplitPath}{wxsplitfunction}\\


@@ -424,14 +425,22 @@ processes.
 
 \membersection{::wxExecute}\label{wxexecute}
 
 
 \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\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}

 
 

-\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}

 
 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
 
 
 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
 

+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
+an array reference.}
+

 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
 
 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
 

+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 3-element list {\tt ( status, output, errors )}, where
+{\tt output} and {\tt errors} are array references.}
+

 Executes another program in Unix or Windows.
 
 The first form takes a command string, such as {\tt "emacs file.txt"}.
 Executes another program in Unix or Windows.
 
 The first form takes a command string, such as {\tt "emacs file.txt"}.


@@ -442,8 +451,9 @@ arguments, terminated by NULL.
 The semantics of the third and fourth versions is different from the first two
 and is described in more details below.
 
 The semantics of the third and fourth versions is different from the first two
 and is described in more details below.
 

-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 flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
+of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
+application waits until the other program has terminated.

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


@@ -461,10 +471,21 @@ 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.
 
 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, 

 \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
 \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when

-the process finishes.
+the process finishes. Specifying this parameter also allows you to redirect the
+standard input and/or output of the process being launched by calling 
+\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
+under Windows the process window is not shown by default (this avoids having to
+flush an unnecessary console for the processes which don't create any windows
+anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
+happening, i.e. with this flag the child process window will be shown normally.
+
+Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
+that the new process is a group leader (this will create a new session if
+needed). Calling \helpref{wxKill}{wxkill} with the argument of -pid where pid
+is the process ID of the new process will kill this process as well as all of
+its children (except those which have started their own session).

 
 Finally, you may use the third overloaded version of this function to execute
 a process (always synchronously) and capture its output in the array
 
 Finally, you may use the third overloaded version of this function to execute
 a process (always synchronously) and capture its output in the array


@@ -474,6 +495,20 @@ the messages from standard error output in the {\it errors} array.
 See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
 \helpref{Exec sample}{sampleexec}.
 
 See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
 \helpref{Exec sample}{sampleexec}.
 

+\wxheading{Parameters}
+
+\docparam{command}{The command to execute and any parameters to pass to it as a
+single string.}
+
+\docparam{argv}{The command to execute should be the first element of this
+array, any additional ones are the command parameters and the array must be
+terminated with a NULL pointer.}
+
+\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC}, 
+{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
+
+\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
+

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


@@ -485,7 +520,7 @@ See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
 Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
 Should only be used in an emergency: normally the top-level frame
 should be deleted (after deleting all other frames) to terminate the
 Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
 Should only be used in an emergency: normally the top-level frame
 should be deleted (after deleting all other frames) to terminate the

-application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
+application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.

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


@@ -561,6 +596,26 @@ See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
 
 <wx/utils.h>
 
 
 <wx/utils.h>
 

+\membersection{::wxShutdown}\label{wxshutdown}
+
+\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}}
+
+This function shuts down or reboots the computer depending on the value of the 
+{\it flags}. Please notice that doing this requires the corresponding access
+rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT)
+and that this function is only implemented under Unix and Win32.
+
+\wxheading{Parameters}
+
+\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}}
+
+\wxheading{Returns}
+
+{\tt TRUE} on success, {\tt FALSE} if an error occured.
+
+\wxheading{Include files}
+
+<wx/utils.h>

 
 \section{Thread functions}\label{threadfunctions}
 
 
 \section{Thread functions}\label{threadfunctions}
 


@@ -627,7 +682,7 @@ threads.
 \helpref{wxFile}{wxfile}\\
 \helpref{wxFileName}{wxfilename}
 
 \helpref{wxFile}{wxfile}\\
 \helpref{wxFileName}{wxfilename}
 

-\membersection{::wxDirExists}\label{wxdirexists}
+\membersection{::wxDirExists}\label{functionwxdirexists}

 
 \func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
 
 
 \func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
 


@@ -640,7 +695,7 @@ Returns TRUE if the directory exists.
 Converts a DOS to a Unix filename by replacing backslashes with forward
 slashes.
 
 Converts a DOS to a Unix filename by replacing backslashes with forward
 slashes.
 

-\membersection{::wxFileExists}\label{wxfileexists}
+\membersection{::wxFileExists}\label{functionwxfileexists}

 
 \func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
 
 
 \func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
 


@@ -1926,7 +1981,7 @@ class instead.
 
 <wx/clipbrd.h>
 
 
 <wx/clipbrd.h>
 

-\membersection{::wxClipboardOpen}\label{wxclipboardopen}
+\membersection{::wxClipboardOpen}\label{functionwxclipboardopen}

 
 \func{bool}{wxClipboardOpen}{\void}
 
 
 \func{bool}{wxClipboardOpen}{\void}
 


@@ -2073,16 +2128,6 @@ See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient},
 
 <wx/dde.h>
 
 
 <wx/dde.h>
 

-\membersection{::wxDisplaySize}\label{wxdisplaysize}
-
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
-
-Gets the physical size of the display in pixels.
-
-\wxheading{Include files}
-
-<wx/gdicmn.h>
-

 \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
 
 \func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
 \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
 
 \func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}


@@ -2210,6 +2255,17 @@ See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxco
 
 <wx/utils.h>
 
 
 <wx/utils.h>
 

+\membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
+
+\func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
+
+Returns the first top level parent of the given window, or in other words, the
+frame or dialog containing it, or {\tt NULL}.
+
+\wxheading{Include files}
+
+<wx/window.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"}}


@@ -2254,21 +2310,11 @@ Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
 
 \func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
 
 
 \func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
 

-This function posts the event to the specified {\it dest} object. The
-difference between sending an event and posting it is that in the first case
-the event is processed before the function returns (in wxWindows, event sending
-is done with \helpref{ProcessEvent}{wxevthandlerprocessevent} function), but in
-the second, the function returns immediately and the event will be processed
-sometime later - usually during the next even loop iteration.
-
-Note that a copy of the {\it event} is made by the function, so the original
-copy can be deleted as soon as function returns. This function can also be used
-to send events between different threads safely. As this function makes a
-copy of the event, the event needs to have a fully implemented Clone() method,
-which may not be the case for all event in wxWindows.
-
-See also \helpref{AddPendingEvent}{wxevthandleraddpendingevent} (which this function
-uses internally).
+In a GUI application, this function posts {\it event} to the specified {\it dest}
+object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
+Otherwise, it dispatches {\it event} immediately using
+\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}.
+See the respective documentation for details (and caveats).

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


@@ -2339,7 +2385,7 @@ See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfig
 
 <wx/utils.h>
 
 
 <wx/utils.h>
 

-\section{Byte order macros}\label{macros}
+\section{Byte order macros}\label{byteordermacros}

 
 The endian-ness issues (that is the difference between big-endian and
 little-endian architectures) are important for the portable programs working
 
 The endian-ness issues (that is the difference between big-endian and
 little-endian architectures) are important for the portable programs working


@@ -2397,7 +2443,7 @@ been compiled on a big-endian architecture, the value will be unchanged.
 Use these macros to read data from and write data to a file that stores
 data in big-endian format.
 
 Use these macros to read data from and write data to a file that stores
 data in big-endian format.
 

-\section{RTTI functions}\label{macros}
+\section{RTTI functions}\label{rttimacros}

 
 wxWindows uses its own RTTI ("run-time type identification") system which
 predates the current standard C++ RTTI and so is kept for backwards
 
 wxWindows uses its own RTTI ("run-time type identification") system which
 predates the current standard C++ RTTI and so is kept for backwards


@@ -2735,7 +2781,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

-\tt{#}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}\label{wxresourceclear}
 perhaps for implementing resource functionality for interpreted languages.
 
 \membersection{::wxResourceClear}\label{wxresourceclear}


@@ -2901,7 +2947,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 \tt{#}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.
 


@@ -3250,14 +3296,14 @@ Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
 
 \membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
 
 
 \membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
 

-\func{wxLongLone}{wxGetLocalTimeMillis}{\void}
+\func{wxLongLong}{wxGetLocalTimeMillis}{\void}

 
 Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
 
 \wxheading{See also}
 
 \helpref{wxDateTime::Now}{wxdatetimenow},\\
 
 Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
 
 \wxheading{See also}
 
 \helpref{wxDateTime::Now}{wxdatetimenow},\\

-\helpref{wxLongLone}{wxlonglong}
+\helpref{wxLongLong}{wxlonglong}

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


@@ -3370,7 +3416,7 @@ because it will not be executed in release mode at all.
 \func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
 
 This macro results in a 
 \func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
 
 This macro results in a 

-\helpref{compile time assertion failure}{wxCOMPILE\_TIME\_ASSERT} if the size
+\helpref{compile time assertion failure}{wxcompiletimeassert} if the size

 of the given type {\it type} is less than {\it size} bits.
 
 You may use it like this, for example:
 of the given type {\it type} is less than {\it size} bits.
 
 You may use it like this, for example:


@@ -3399,7 +3445,7 @@ Assert macro with message. An error message will be generated if the condition i
 \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
 
 Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
 \func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
 
 Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the

-specified {\it condition| is false. The compiler error message should include
+specified {\it condition} is false. The compiler error message should include

 the {\it msg} identifier - please note that it must be a valid C++ identifier
 and not a string unlike in the other cases.
 
 the {\it msg} identifier - please note that it must be a valid C++ identifier
 and not a string unlike in the other cases.