Fix spelling in the comments in wxPropertyGrid code.

[wxWidgets.git] / interface / wx / utils.h

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 534b610ea66dee07b33cefe800b4918e51392fbe..34a9e15347460572c0d182de67325c60e1614f1c 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -3,9 +3,59 @@
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Signal constants used by wxProcess.
+*/
+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
+};
+
+/**
+    Return values for wxProcess::Kill.
+*/
+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
+};
+
+enum wxKillFlags
+{
+    wxKILL_NOCHILDREN = 0,  //!< don't kill children
+    wxKILL_CHILDREN = 1     //!< kill children
+};
+
+enum wxShutdownFlags
+{
+    wxSHUTDOWN_FORCE    = 1, //!< can be combined with other flags (MSW-only)
+    wxSHUTDOWN_POWEROFF = 2, //!< power off the computer
+    wxSHUTDOWN_REBOOT   = 4, //!< shutdown and reboot
+    wxSHUTDOWN_LOGOFF   = 8  //!< close session (currently MSW-only)
+};
+
+

 /**
     @class wxWindowDisabler
 
 /**
     @class wxWindowDisabler
 


@@ -37,6 +87,14 @@ public:
     /**
         Disables all top level windows of the applications with the exception
         of @a winToSkip if it is not @NULL.
     /**
         Disables all top level windows of the applications with the exception
         of @a winToSkip if it is not @NULL.

+
+        Notice that under MSW if @a winToSkip appears in the taskbar, the user
+        will be able to close the entire application (even though its main
+        window is disabled) by right clicking on the taskbar icon and selecting
+        the appropriate "Close" command from the context menu. To prevent this
+        from happening you may want to use wxFRAME_TOOL_WINDOW, if applicable,
+        or wxFRAME_NO_TASKBAR style when creating the window that will remain
+        enabled.

     */
     wxWindowDisabler(wxWindow* winToSkip);
 
     */
     wxWindowDisabler(wxWindow* winToSkip);
 


@@ -106,7 +164,7 @@ public:
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+void wxBeginBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);

 
 /**
     Changes the cursor back to the original cursor, for all windows in the
 
 /**
     Changes the cursor back to the original cursor, for all windows in the


@@ -134,6 +192,8 @@ bool wxIsBusy();
     @note This function is categorized as a GUI one and so is not thread-safe.
 
     @header{wx/utils.h}
     @note This function is categorized as a GUI one and so is not thread-safe.
 
     @header{wx/utils.h}

+
+    @library{wxcore}

 */
 void wxBell();
 
 */
 void wxBell();
 


@@ -146,9 +206,29 @@ void wxBell();
 
     @since 2.9.0
 
 
     @since 2.9.0
 

+    @see wxGetLibraryVersionInfo()
+
+    @header{wx/utils.h}
+*/
+void wxInfoMessageBox(wxWindow* parent);
+
+//@}
+
+/** @addtogroup group_funcmacro_version */
+//@{
+
+/**
+    Get wxWidgets version information.
+
+    @since 2.9.2
+
+    @see wxVersionInfo
+

     @header{wx/utils.h}
     @header{wx/utils.h}

+
+    @library{wxcore}

 */
 */

-void wxInfoMessageBox(wxWindow parent = NULL);
+wxVersionInfo wxGetLibraryVersionInfo();

 
 //@}
 
 
 //@}
 


@@ -157,6 +237,18 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 /** @addtogroup group_funcmacro_env */
 //@{
 
 /** @addtogroup group_funcmacro_env */
 //@{
 

+/**
+    A map type containing environment variables names and values.
+
+    This type is used with wxGetEnvMap() function and wxExecuteEnv structure
+    optionally passed to wxExecute().
+
+    @since 2.9.2
+
+    @header{wx/utils.h}
+*/
+typedef wxStringToStringHashMap wxEnvVariableHashMap;
+

 /**
     This is a macro defined as @c getenv() or its wide char version in Unicode
     mode.
 /**
     This is a macro defined as @c getenv() or its wide char version in Unicode
     mode.


@@ -169,8 +261,9 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 wxChar* wxGetenv(const wxString& var);
 
 /**
 wxChar* wxGetenv(const wxString& var);
 
 /**

-    Returns the current value of the environment variable @c var in @c value.
-    @c value may be @NULL if you just want to know if the variable exists and
+    Returns the current value of the environment variable @a var in @a value.
+
+    @a value may be @NULL if you just want to know if the variable exists and

     are not interested in its value.
 
     Returns @true if the variable exists, @false otherwise.
     are not interested in its value.
 
     Returns @true if the variable exists, @false otherwise.


@@ -180,10 +273,25 @@ wxChar* wxGetenv(const wxString& var);
 bool wxGetEnv(const wxString& var, wxString* value);
 
 /**
 bool wxGetEnv(const wxString& var, wxString* value);
 
 /**

-    Sets the value of the environment variable @c var (adding it if necessary)
-    to @c value.
-
-    Returns @true on success.
+    Sets the value of the environment variable @a var (adding it if necessary)
+    to @a value.
+
+    Notice that under Windows platforms the program may have two different
+    environment blocks: the first one is that of a Windows process and is
+    always present, but the CRT may maintain its own independent copy of the
+    environment. wxSetEnv() will always update the first copy, which means that
+    wxGetEnv(), which uses it directly, will always return the expected value
+    after this call. But wxSetEnv() only updates the second copy for some
+    compilers/CRT implementations (currently only MSVC and MinGW which uses the
+    same MSVC CRT) and so using wxGetenv() (notice the difference in case) may
+    not return the updated value.
+
+    @param var
+        The environment variable to be set, must not contain @c '=' character.
+    @param value
+        New value of the variable.
+    @return
+        @true on success or @false if changing the value failed.

 
     @see wxUnsetEnv()
 
 
     @see wxUnsetEnv()
 


@@ -192,8 +300,9 @@ bool wxGetEnv(const wxString& var, wxString* value);
 bool wxSetEnv(const wxString& var, const wxString& value);
 
 /**
 bool wxSetEnv(const wxString& var, const wxString& value);
 
 /**

-    Removes the variable @c var from the environment. wxGetEnv() will return
-    @NULL after the call to this function.
+    Removes the variable @a var from the environment.
+
+    wxGetEnv() will return @NULL after the call to this function.

 
     Returns @true on success.
 
 
     Returns @true on success.
 


@@ -201,6 +310,22 @@ bool wxSetEnv(const wxString& var, const wxString& value);
 */
 bool wxUnsetEnv(const wxString& var);
 
 */
 bool wxUnsetEnv(const wxString& var);
 

+/**
+    Fill a map with the complete content of current environment.
+
+    The map will contain the environment variable names as keys and their
+    values as values.
+
+    @param map
+        The environment map to fill, must be non-@NULL.
+    @return
+        @true if environment was successfully retrieved or @false otherwise.
+
+    @header{wx/utils.h}
+
+    @since 2.9.2
+*/
+bool wxGetEnvMap(wxEnvVariableHashMap *map);

 //@}
 
 
 //@}
 
 


@@ -281,6 +406,9 @@ void wxEnableTopLevelWindows(bool enable = true);
     Find the deepest window at the given mouse position in screen coordinates,
     returning the window if found, or @NULL if not.
 
     Find the deepest window at the given mouse position in screen coordinates,
     returning the window if found, or @NULL if not.
 

+    This function takes child windows at the given position into account even
+    if they are disabled. The hidden children are however skipped by it.
+

     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowAtPoint(const wxPoint& pt);


@@ -390,24 +518,92 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
 /**
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
 /**

-    Loads a user-defined Windows resource as a string. If the resource is
-    found, the function creates a new character array and copies the data into
-    it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
+    Loads an object from Windows resource file.

 
 

-    The resource must be defined in the @c .rc file using the following syntax:
+    This function loads the resource with the given name and type from the
+    resources embedded into a Windows application.

 
 

+    The typical use for it is to load some data from the data files embedded
+    into the program itself. For example, you could have the following fragment
+    in your @c .rc file

     @code
     @code

-    myResource TEXT file.ext
+        mydata  MYDATA  "myfile.dat"
+    @endcode
+    and then use it in the following way:
+    @code
+        const void* data = NULL;
+        size_t size = 0;
+        if ( !wxLoadUserResource(&data, &size, "mydata", "MYDATA") ) {
+            ... handle error ...
+        }
+        else {
+            // Use the data in any way, for example:
+            wxMemoryInputStream is(data, size);
+            ... read the data from stream ...
+        }

     @endcode
 
     @endcode
 

-    Where @c file.ext is a file that the resource compiler can find.
+    @param outData Filled with the pointer to the data on successful return.
+        Notice that this pointer does @em not need to be freed by the caller.
+    @param outLen Filled with the length of the data in bytes.
+    @param resourceName The name of the resource to load.
+    @param resourceType The type of the resource in usual Windows format, i.e.
+        either a real string like "MYDATA" or an integer created by the
+        standard Windows @c MAKEINTRESOURCE() macro, including any constants
+        for the standard resources types like @c RT_RCDATA.
+    @param module The @c HINSTANCE of the module to load the resources from.
+        The current module is used by default.
+    @return true if the data was loaded from resource or false if it couldn't
+        be found (in which case no error is logged) or was found but couldn't
+        be loaded (which is unexpected and does result in an error message).

 
     This function is available under Windows only.
 
 
     This function is available under Windows only.
 

+    @library{wxbase}
+
+    @header{wx/utils.h}
+
+    @since 2.9.1
+ */
+bool
+wxLoadUserResource(const void **outData,
+                   size_t *outLen,
+                   const wxString& resourceName,
+                   const wxChar* resourceType = "TEXT",
+                   WXHINSTANCE module = 0);
+
+/**
+    Loads a user-defined Windows resource as a string.
+
+    This is a wrapper for the general purpose overload wxLoadUserResource(const
+    void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be
+    more convenient for the string data, but does an extra copy compared to the
+    general version.
+
+    @param resourceName The name of the resource to load.
+    @param resourceType The type of the resource in usual Windows format, i.e.
+        either a real string like "MYDATA" or an integer created by the
+        standard Windows @c MAKEINTRESOURCE() macro, including any constants
+        for the standard resources types like @c RT_RCDATA.
+    @param pLen Filled with the length of the returned buffer if it is
+        non-@NULL. This parameter should be used if NUL characters can occur in
+        the resource data. It is new since wxWidgets 2.9.1
+    @param module The @c HINSTANCE of the module to load the resources from.
+        The current module is used by default. This parameter is new since
+        wxWidgets 2.9.1.
+    @return A pointer to the data to be <tt>delete[]<tt>d by caller on success
+        or @NULL on error.
+
+    This function is available under Windows only.
+
+    @library{wxbase}
+

     @header{wx/utils.h}
 */
     @header{wx/utils.h}
 */

-wxString wxLoadUserResource(const wxString& resourceName,
-                            const wxString& resourceType = "TEXT");
+char* wxLoadUserResource(const wxString& resourceName,
+                         const wxChar* resourceType = "TEXT",
+                         int* pLen = NULL,
+                         WXHINSTANCE module = 0);

 
 /**
     @deprecated Replaced by wxWindow::Close(). See the
 
 /**
     @deprecated Replaced by wxWindow::Close(). See the


@@ -428,19 +624,19 @@ void wxPostDelete(wxObject* object);
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-extern "C"
-{
-typedef int (wxCMPFUNC_CONV *CMPFUNCDATA)(const void* pItem1, const void* pItem2, const void* user_data);
-}
+typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data);

 
 /**
 
 /**

-    Function for performing a qsort operation including a user data
-    parameter.
+    Function implementing quick sort algorithm.
+
+    This function sorts @a total_elems objects of size @a size located at @a
+    pbase. It uses @a cmp function for comparing them and passes @a user_data
+    pointer to the comparison function each time it's called.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxQsort(void *const pbase, size_t total_elems,
-             size_t size, CMPFUNCDATA cmp, const void* user_data);
+void wxQsort(void* pbase, size_t total_elems,
+             size_t size, wxSortCallback cmp, const void* user_data);

 
 
 /**
 
 
 /**


@@ -455,6 +651,22 @@ void wxQsort(void *const pbase, size_t total_elems,
 */
 void wxSetDisplayName(const wxString& displayName);
 
 */
 void wxSetDisplayName(const wxString& displayName);
 

+
+/**
+   flags for wxStripMenuCodes
+*/
+enum
+{
+    // strip '&' characters
+    wxStrip_Mnemonics = 1,
+
+    // strip everything after '\t'
+    wxStrip_Accel = 2,
+
+    // strip everything (this is the default)
+    wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
+};
+

 /**
     Strips any menu codes from @a str and returns the result.
 
 /**
     Strips any menu codes from @a str and returns the result.
 


@@ -633,8 +845,34 @@ bool wxGetUserName(char* buf, int sz);
 wxString wxGetOsDescription();
 
 /**
 wxString wxGetOsDescription();
 
 /**

-    Gets the version and the operating system ID for currently running OS. See
-    wxPlatformInfo for more details about wxOperatingSystemId.
+    Gets the version and the operating system ID for currently running OS. 
+    The returned wxOperatingSystemId value can be used for a basic categorization
+    of the OS family; the major and minor version numbers allows to detect a specific
+    system.
+    
+    For Unix-like systems (@c wxOS_UNIX) the major and minor version integers will 
+    contain the kernel major and minor version numbers (as returned by the
+    'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.
+
+    For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the
+    natural version numbers associated with the OS; e.g. "10" and "6" if the machine
+    is using Mac OS X Snow Leopard.    
+    
+    For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will 
+    contain the following values:
+    @beginTable
+    @row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>}
+    @row3col{Windows 7,                 6, 1}
+    @row3col{Windows Server 2008 R2,    6, 1}
+    @row3col{Windows Server 2008,       6, 0}
+    @row3col{Windows Vista,             6, 0}
+    @row3col{Windows Server 2003 R2,    5, 2}
+    @row3col{Windows Server 2003,       5, 2}
+    @row3col{Windows XP,                5, 1}
+    @row3col{Windows 2000,              5, 0}
+    @endDefList
+    See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a>
+    for more info about the values above.

 
     @see wxGetOsDescription(), wxPlatformInfo
 
 
     @see wxGetOsDescription(), wxPlatformInfo
 


@@ -668,6 +906,23 @@ bool wxIsPlatform64Bit();
 */
 bool wxIsPlatformLittleEndian();
 
 */
 bool wxIsPlatformLittleEndian();
 

+/**
+    Returns a structure containing informations about the currently running
+    Linux distribution.
+    
+    This function uses the @c lsb_release utility which is part of the 
+    <tt>Linux Standard Base Core</tt> specification 
+    (see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB 
+    release 1.0 (released in 2001).
+    The @c lsb_release utility is very common on modern Linux distributions but in
+    case it's not available, then this function will return a ::wxLinuxDistributionInfo
+    structure containing empty strings.
+    
+    This function is Linux-specific and is only available when the @c __LINUX__
+    symbol is defined.
+*/
+wxLinuxDistributionInfo wxGetLinuxDistributionInfo();
+

 //@}
 
 
 //@}
 
 


@@ -675,6 +930,115 @@ bool wxIsPlatformLittleEndian();
 /** @addtogroup group_funcmacro_procctrl */
 //@{
 
 /** @addtogroup group_funcmacro_procctrl */
 //@{
 

+/**
+    @struct wxExecuteEnv
+
+    This structure can optionally be passed to wxExecute() to specify
+    additional options to use for the child process.
+
+    @since 2.9.2
+
+    @header{wx/utils.h}
+*/
+struct wxExecuteEnv
+{
+    /**
+        The initial working directory for the new process.
+
+        If this field is empty, the current working directory of this process
+        is used.
+    */
+    wxString cwd;
+
+    /**
+        The environment variable map.
+
+        If the map is empty, the environment variables of the current process
+        are also used for the child one, otherwise only the variables defined
+        in this map are used.
+    */
+    wxEnvVariableHashMap env;
+};
+
+/**
+    Bit flags that can be used with wxExecute().
+ */
+enum
+{
+    /**
+        Execute the process asynchronously.
+
+        Notice that, due to its value, this is the default.
+     */
+    wxEXEC_ASYNC    = 0,
+
+    /**
+        Execute the process synchronously.
+     */
+    wxEXEC_SYNC     = 1,
+
+    /**
+        Always show the child process console under MSW.
+
+        The child console is hidden by default if the child IO is redirected,
+        this flag allows to change this and show it nevertheless.
+
+        This flag is ignored under the other platforms.
+     */
+    wxEXEC_SHOW_CONSOLE   = 2,
+
+    /**
+        Make the new process a group leader.
+
+        Under Unix, if the process is the group leader then passing
+        wxKILL_CHILDREN to wxKill() kills all children as well as pid.
+
+        Under MSW, applies only to console applications and is only supported
+        under NT family (i.e. not under Windows 9x). It corresponds to the
+        native @c CREATE_NEW_PROCESS_GROUP and, in particular, ensures that
+        Ctrl-Break signals will be sent to all children of this process as well
+        to the process itself. Support for this flag under MSW was added in
+        version 2.9.4 of wxWidgets.
+     */
+    wxEXEC_MAKE_GROUP_LEADER = 4,
+
+    /**
+        Don't disable the program UI while running the child synchronously.
+
+        By default synchronous execution disables all program windows to avoid
+        that the user interacts with the program while the child process is
+        running, you can use this flag to prevent this from happening.
+
+        This flag can only be used with ::wxEXEC_SYNC.
+     */
+    wxEXEC_NODISABLE = 8,
+
+    /**
+        Don't dispatch events while the child process is executed.
+
+        By default, the event loop is run while waiting for synchronous
+        execution to complete and this flag can be used to simply block the
+        main process until the child process finishes
+
+        This flag can only be used with ::wxEXEC_SYNC.
+     */
+    wxEXEC_NOEVENTS = 16,
+
+    /**
+        Hide child process console under MSW.
+
+        Under MSW, hide the console of the child process if it has one,
+        even if its IO is not redirected.
+
+        This flag is ignored under the other platforms.
+     */
+    wxEXEC_HIDE_CONSOLE = 32,
+
+    /**
+        Convenient synonym for flags given system()-like behaviour.
+     */
+    wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
+};

 /**
     Executes another program in Unix or Windows.
 
 /**
     Executes another program in Unix or Windows.
 


@@ -706,18 +1070,22 @@ bool wxIsPlatformLittleEndian();
     wxProcess::OnTerminate() will be called when the process finishes.
     Specifying this parameter also allows you to redirect the standard input
     and/or output of the process being launched by calling
     wxProcess::OnTerminate() will be called when the process finishes.
     Specifying this parameter also allows you to redirect the standard input
     and/or output of the process being launched by calling

-    wxProcess::Redirect(). 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 @c wxEXEC_NOHIDE flag can be used to prevent this from
-    happening, i.e. with this flag the child process window will be shown
-    normally.
+    wxProcess::Redirect().
+
+    Under Windows, when launching a console process its console is shown by
+    default but hidden if its IO is redirected. Both of these default
+    behaviours may be overridden: if ::wxEXEC_HIDE_CONSOLE is specified, the
+    console will never be shown. If ::wxEXEC_SHOW_CONSOLE is used, the console
+    will be shown even if the child process IO is redirected. Neither of these
+    flags affect non-console Windows applications or does anything under the
+    other systems.

 
     Under Unix the flag @c 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 wxKill() passing wxKILL_CHILDREN will kill this process as
     well as all of its children (except those which have started their own
 
     Under Unix the flag @c 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 wxKill() passing wxKILL_CHILDREN will kill this process as
     well as all of its children (except those which have started their own

-    session).
+    session). Under MSW, this flag can be used with console processes only and
+    corresponds to the native @c CREATE_NEW_PROCESS_GROUP flag.

 
     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
     place while the child process is running. It should be only used for very
 
     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
     place while the child process is running. It should be only used for very


@@ -735,11 +1103,15 @@ bool wxIsPlatformLittleEndian();
         string, i.e. "emacs file.txt".
     @param flags
         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
         string, i.e. "emacs file.txt".
     @param flags
         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include

-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
-        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
-        their combination, in wxEXEC_SYNC case.
+        wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, wxEXEC_MAKE_GROUP_LEADER (in
+        either case) or wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK,
+        which is equal to their combination, in wxEXEC_SYNC case.

     @param callback
         An optional pointer to wxProcess.
     @param callback
         An optional pointer to wxProcess.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()


@@ -747,14 +1119,12 @@ bool wxIsPlatformLittleEndian();
     @header{wx/utils.h}
 
     @beginWxPerlOnly
     @header{wx/utils.h}
 
     @beginWxPerlOnly

-    This function is called @c Wx::ExecuteStdoutStderr and it only takes the
-    @a command argument, and returns a 3-element list (@c status, @c output,
-    @c errors), where @c output and @c errors are array references.
+    In wxPerl this function is called @c Wx::ExecuteCommand.

     @endWxPerlOnly
 */
 long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
     @endWxPerlOnly
 */
 long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,

-                wxProcess* callback = NULL);
-
+                wxProcess* callback = NULL,
+                const wxExecuteEnv* env = NULL);

 //@}
 
 /** @addtogroup group_funcmacro_procctrl */
 //@}
 
 /** @addtogroup group_funcmacro_procctrl */


@@ -771,22 +1141,29 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
         additional ones are the command parameters and the array must be
         terminated with a @NULL pointer.
     @param flags
         additional ones are the command parameters and the array must be
         terminated with a @NULL pointer.
     @param flags

-        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
-        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
-        their combination, in wxEXEC_SYNC case.
+        Same as for wxExecute(const wxString&,int,wxProcess*) overload.

     @param callback
         An optional pointer to wxProcess.
     @param callback
         An optional pointer to wxProcess.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}

+
+    @beginWxPerlOnly
+    In wxPerl this function is called @c Wx::ExecuteArgs.
+    @endWxPerlOnly

 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,

-                wxProcess* callback = NULL);
+                wxProcess* callback = NULL,
+                const wxExecuteEnv *env = NULL);

 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,

-                wxProcess* callback = NULL);
+                wxProcess* callback = NULL,
+                const wxExecuteEnv *env = NULL);

 //@}
 
 /** @addtogroup group_funcmacro_procctrl */
 //@}
 
 /** @addtogroup group_funcmacro_procctrl */


@@ -806,24 +1183,33 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
     @param output
         The string array where the stdout of the executed process is saved.
     @param flags
     @param output
         The string array where the stdout of the executed process is saved.
     @param flags

-        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
-        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
-        their combination, in wxEXEC_SYNC case.
+        Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}

+
+    @beginWxPerlOnly
+    This function is called @c Wx::ExecuteStdout: it only takes the
+    @a command argument, and returns a 2-element list (@c status, @c output),
+    where @c output in an array reference.
+    @endWxPerlOnly

 */
 */

-long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
+long wxExecute(const wxString& command, wxArrayString& output, int flags = 0,
+                const wxExecuteEnv *env = NULL);

 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
     please see its documentation for general information.
 
     This version adds the possibility to additionally capture the messages from
 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
     please see its documentation for general information.
 
     This version adds the possibility to additionally capture the messages from

-    standard error output in the @a errors array.
+    standard error output in the @a errors array. As with the above overload
+    capturing standard output only, execution is always synchronous.

 
     @param command
         The command to execute and any parameters to pass to it as a single
 
     @param command
         The command to execute and any parameters to pass to it as a single


@@ -833,18 +1219,26 @@ long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
     @param errors
         The string array where the stderr of the executed process is saved.
     @param flags
     @param errors
         The string array where the stderr of the executed process is saved.
     @param flags

-        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
-        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
-        their combination, in wxEXEC_SYNC case.
+        Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}

+
+    @beginWxPerlOnly
+    This function is called @c Wx::ExecuteStdoutStderr: it only takes the
+    @a command argument, and returns a 3-element list (@c status, @c output,
+    @c errors), where @c output and @c errors are array references.
+    @endWxPerlOnly

 */
 long wxExecute(const wxString& command, wxArrayString& output,
 */
 long wxExecute(const wxString& command, wxArrayString& output,

-                wxArrayString& errors, int flags = 0);
+                wxArrayString& errors, int flags = 0,
+                const wxExecuteEnv *env = NULL);

 
 /**
     Returns the number uniquely identifying the current process in the system.
 
 /**
     Returns the number uniquely identifying the current process in the system.


@@ -856,7 +1250,9 @@ unsigned long wxGetProcessId();
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the

-    process with PID @a pid. The valid signal values are:
+    process with PID @a pid.
+
+    The valid signal values are:

 
     @code
     enum wxSignal
 
     @code
     enum wxSignal


@@ -885,7 +1281,7 @@ unsigned long wxGetProcessId();
     @c wxSIGTERM under Windows.
 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
     @c wxSIGTERM under Windows.
 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,

-    it will be filled with a value of the the @c wxKillError enum:
+    it will be filled with a value from the @c wxKillError enum:

 
     @code
     enum wxKillError
 
     @code
     enum wxKillError


@@ -908,8 +1304,8 @@ unsigned long wxGetProcessId();
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-int wxKill(long pid, int sig = wxSIGTERM,
-            wxKillError rc = NULL, int flags = 0);
+int wxKill(long pid, wxSignal sig = wxSIGTERM,
+            wxKillError* rc = NULL, int flags = wxKILL_NOCHILDREN);

 
 /**
     Executes a command in an interactive shell window. If no command is
 
 /**
     Executes a command in an interactive shell window. If no command is


@@ -919,7 +1315,7 @@ int wxKill(long pid, int sig = wxSIGTERM,
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxShell(const wxString& command = NULL);
+bool wxShell(const wxString& command = wxEmptyString);

 
 /**
     This function shuts down or reboots the computer depending on the value of
 
 /**
     This function shuts down or reboots the computer depending on the value of