Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 41ca90a8b4da0f3745dc733edd6a3ba310d69c49..120ed37cc3a119f8c7af7602a04f5e4ffe0249dc 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -3,12 +3,11 @@
 // 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

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

-    @wxheader{utils.h}

 
     This class disables all windows of the application (may be with the
     exception of one of them) in its constructor and enables them back in its
 
     This class disables all windows of the application (may be with the
     exception of one of them) in its constructor and enables them back in its


@@ -38,6 +37,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);
 


@@ -51,7 +58,6 @@ public:
 
 /**
     @class wxBusyCursor
 
 /**
     @class wxBusyCursor

-    @wxheader{utils.h}

 
     This class makes it easy to tell your user that the program is temporarily
     busy. Just create a wxBusyCursor object on the stack, and within the
 
     This class makes it easy to tell your user that the program is temporarily
     busy. Just create a wxBusyCursor object on the stack, and within the


@@ -80,7 +86,7 @@ public:
     /**
         Constructs a busy cursor object, calling wxBeginBusyCursor().
     */
     /**
         Constructs a busy cursor object, calling wxBeginBusyCursor().
     */

-    wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+    wxBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);

 
     /**
         Destroys the busy cursor object, calling wxEndBusyCursor().
 
     /**
         Destroys the busy cursor object, calling wxEndBusyCursor().


@@ -90,93 +96,12 @@ public:
 
 
 
 
 
 

-/**
-    @class wxMouseState
-    @wxheader{utils.h}
-
-    Represents the mouse state.
-
-    The methods of this class generally mirror the corresponding methods of
-    wxMouseEvent.
-
-    This class is implemented entirely in @<wx/utils.h@>, meaning no extra
-    library needs to be linked to use this class.
-
-    @category{misc}
-
-    @see wxGetMouseState()
- */
-class wxMouseState
-{
-public:
-    /**
-        Default constructor.
-    */
-    wxMouseState();
-
-    /**
-        Returns X coordinate of the physical mouse event position.
-    */
-    wxCoord GetX() const;
-    /**
-        Returns Y coordinate of the physical mouse event position.
-    */
-    wxCoord GetY() const;
-    /**
-        Returns the physical mouse position.
-    */
-    wxPoint GetPosition() const;
-
-    /**
-        Returns @true if the left mouse button changed to down.
-    */
-    bool LeftDown() const;
-    /**
-        Returns @true if the middle mouse button changed to down.
-    */
-    bool MiddleDown() const;
-    /**
-        Returns @true if the right mouse button changed to down.
-    */
-    bool RightDown() const;
-    /**
-        Returns @true if the first extra button mouse button changed to down.
-    */
-    bool Aux1Down() const;
-    /**
-        Returns @true if the second extra button mouse button changed to down.
-    */
-    bool Aux2Down() const;
-
-    /**
-        Returns @true if the control key is down.
-    */
-    bool ControlDown() const;
-    /**
-        Returns @true if the shift key is down.
-    */
-    bool ShiftDown() const;
-    /**
-        Returns @true if the alt key is down.
-    */
-    bool AltDown() const;
-    /**
-        Returns @true if the meta key is down.
-    */
-    bool MetaDown() const;
-    /**
-        Same as MetaDown() under Mac systems, ControlDown() for the others.
-    */
-    bool CmdDown() const;
-};
-
-

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -189,7 +114,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


@@ -228,18 +153,45 @@ void wxBell();
     doesn't otherwise handle this event.
 
     @since 2.9.0
     doesn't otherwise handle this event.
 
     @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();

 
 //@}
 
 
 
 
 //@}
 
 
 

-/** @ingroup 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.


@@ -252,8 +204,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.


@@ -263,10 +216,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()
 


@@ -275,8 +243,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.
 


@@ -284,11 +253,27 @@ 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);

 //@}
 
 
 
 //@}
 
 
 

-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */

 //@{
 
 /**
 //@{
 
 /**


@@ -425,12 +410,39 @@ long wxNewId();
 void wxRegisterId(long id);
 
 /**
 void wxRegisterId(long id);
 
 /**

-    Opens the @a url in user's default browser. If the @a flags parameter
-    contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
-    (currently this is only supported under Windows). The @a url may also be a
-    local file path (with or without the "file://" prefix), if it doesn't
-    correspond to an existing file and the URL has no scheme "http://" is
-    prepended to it by default.
+    Opens the @a document in the application associated with the files of this
+    type.
+
+    The @a flags parameter is currently not used
+
+    Returns @true if the application was successfully launched.
+
+    @see wxLaunchDefaultBrowser(), wxExecute()
+
+    @header{wx/utils.h}
+*/
+bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
+
+/**
+    Opens the @a url in user's default browser.
+
+    If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
+    window is opened for the URL (currently this is only supported under
+    Windows).
+
+    And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
+    a busy cursor is shown while the browser is being launched (using
+    wxBusyCursor).
+
+    The parameter @a url is interpreted as follows:
+    - if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "mailto:")
+      it is passed to the appropriate browser configured in the user system.
+    - if it has no valid scheme (e.g. it's a local file path without the @c "file:"
+      prefix), then ::wxFileExists and ::wxDirExists are used to test if it's a
+      local file/directory; if it is, then the browser is called with the
+      @a url parameter eventually prefixed by @c "file:".
+    - if it has no valid scheme and it's not a local file/directory, then @c "http:"
+      is prepended and the browser is called.

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


@@ -439,6 +451,8 @@ void wxRegisterId(long id);
           may be used for local URLs while another one may be used for remote
           URLs).
 
           may be used for local URLs while another one may be used for remote
           URLs).
 

+    @see wxLaunchDefaultApplication(), wxExecute()
+

     @header{wx/utils.h}
 */
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
     @header{wx/utils.h}
 */
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);


@@ -476,6 +490,27 @@ wxString wxLoadUserResource(const wxString& resourceName,
 */
 void wxPostDelete(wxObject* object);
 
 */
 void wxPostDelete(wxObject* object);
 

+
+/**
+    Compare function type for use with wxQsort()
+
+    @header{wx/utils.h}
+*/
+extern "C"
+{
+typedef int (wxCMPFUNC_CONV *CMPFUNCDATA)(const void* pItem1, const void* pItem2, const void* user_data);
+}
+
+/**
+    Function for performing a qsort operation including a user data
+    parameter.
+
+    @header{wx/utils.h}
+*/
+void wxQsort(void *const pbase, size_t total_elems,
+             size_t size, CMPFUNCDATA cmp, const void* user_data);
+
+

 /**
     Under X only, sets the current display name. This is the X host and display
     name such as "colonsay:0.0", and the function indicates which display
 /**
     Under X only, sets the current display name. This is the X host and display
     name such as "colonsay:0.0", and the function indicates which display


@@ -494,7 +529,7 @@ void wxSetDisplayName(const wxString& displayName);
     By default, the functions strips both the mnemonics character (@c '&')
     which is used to indicate a keyboard shortkey, and the accelerators, which
     are used only in the menu items and are separated from the main text by the
     By default, the functions strips both the mnemonics character (@c '&')
     which is used to indicate a keyboard shortkey, and the accelerators, which
     are used only in the menu items and are separated from the main text by the

-    @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
+    @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or

     @c wxStrip_Accel to strip only the former or the latter part, respectively.
 
     Notice that in most cases wxMenuItem::GetLabelFromText() or
     @c wxStrip_Accel to strip only the former or the latter part, respectively.
 
     Notice that in most cases wxMenuItem::GetLabelFromText() or


@@ -508,7 +543,7 @@ wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
 
 
 
 
 
 

-/** @ingroup group_funcmacro_networkuseros */
+/** @addtogroup group_funcmacro_networkuseros */

 //@{
 
 /**
 //@{
 
 /**


@@ -598,7 +633,7 @@ wxString wxGetFullHostName();
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetUserHome(const wxString& user = "");
+wxString wxGetUserHome(const wxString& user = wxEmptyString);

 
 /**
     This function returns the "user id" also known as "login name" under Unix
 
 /**
     This function returns the "user id" also known as "login name" under Unix


@@ -666,8 +701,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
 


@@ -701,13 +762,60 @@ 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();
+

 //@}
 
 
 
 //@}
 
 
 

-/** @ingroup 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;
+};
+

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


@@ -773,23 +881,26 @@ bool wxIsPlatformLittleEndian();
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.
         their combination, in wxEXEC_SYNC case.
     @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
+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

 
     @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);

 //@}
 
 //@}
 

-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */

 //@{
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
 //@{
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),


@@ -809,16 +920,29 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.
         their combination, in wxEXEC_SYNC case.
     @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}
 
     @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);

 //@}
 
 //@}
 

-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */

 //@{
 
 /**
 //@{
 
 /**


@@ -832,37 +956,69 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
     @param command
         The command to execute and any parameters to pass to it as a single
         string.
     @param command
         The command to execute and any parameters to pass to it as a single
         string.

+    @param output
+        The string array where the stdout of the executed process is saved.

     @param flags
     @param flags

-        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+        May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or

         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to

-        their combination, in wxEXEC_SYNC case.
+        their combination. wxEXEC_SYNC is always implicitly added to the flags.
+    @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}
 
     @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
         string.
 
     @param command
         The command to execute and any parameters to pass to it as a single
         string.

+    @param output
+        The string array where the stdout of the executed process is saved.
+    @param errors
+        The string array where the stderr of the executed process is saved.

     @param flags
     @param flags

-        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
-        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+        May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or

         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to

-        their combination, in wxEXEC_SYNC case.
+        their combination. wxEXEC_SYNC is always implicitly added to the flags.
+    @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}
 
     @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.


@@ -874,7 +1030,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


@@ -903,7 +1061,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


@@ -926,8 +1084,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


@@ -937,30 +1095,34 @@ 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
     the @a flags.
 
 
 /**
     This function shuts down or reboots the computer depending on the value of
     the @a flags.
 

-    @note Doing this requires the corresponding access rights (superuser under
-          Unix, SE_SHUTDOWN privilege under Windows NT) and that this function
-          is only implemented under Unix and Win32.
+    @note Note that performing the shutdown requires the corresponding access
+        rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT)
+        and that this function is only implemented under Unix and MSW.

 
     @param flags
 
     @param flags

-        Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT
+        One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
+        @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
+        combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by
+        forcefully terminating all the applications. As doing this can result
+        in a data loss, this flag shouldn't be used unless really necessary.

 
     @return @true on success, @false if an error occurred.
 
     @header{wx/utils.h}
 */
 
     @return @true on success, @false if an error occurred.
 
     @header{wx/utils.h}
 */

-bool wxShutdown(wxShutdownFlags flags);
+bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);

 
 //@}
 
 
 
 
 //@}
 
 
 

-/** @ingroup group_funcmacro_time */
+/** @addtogroup group_funcmacro_time */

 //@{
 
 /**
 //@{
 
 /**