group wxPlatformInfo functions for easier browsing; add more descriptions; link the...

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 534b610ea66dee07b33cefe800b4918e51392fbe..d8a7bdd01c78116ae1bc061cfa9e31080fe4bb2e 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -169,8 +169,9 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 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.
@@ -180,10 +181,24 @@ wxChar* wxGetenv(const wxString& var);
 bool wxGetEnv(const wxString& var, wxString* value);
 
 /**
-    Sets the value of the environment variable @c var (adding it if necessary)
-    to @c value.
+    Sets the value of the environment variable @a var (adding it if necessary)
+    to @a value.
 
-    Returns @true on success.
+    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 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()
 
@@ -192,8 +207,9 @@ bool wxGetEnv(const wxString& var, 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.
 
@@ -806,10 +822,9 @@ 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
-        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
-        their combination, in wxEXEC_SYNC case.
+        their combination. wxEXEC_SYNC is always implicitly added to the flags.
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
@@ -823,7 +838,8 @@ long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
     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
@@ -833,10 +849,9 @@ 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
-        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
-        their combination, in wxEXEC_SYNC case.
+        their combination. wxEXEC_SYNC is always implicitly added to the flags.
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()