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);
 
 /**
 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 +181,24 @@ 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.
+    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()
 
 
     @see wxUnsetEnv()
 


@@ -192,8 +207,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.
 


@@ -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
     @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
         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()
 
     @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
     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,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
     @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
         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()
 
     @see wxShell(), wxProcess, @ref page_samples_exec,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()