Must clear property selection in wxPGProperty::SetChoices() or risk a crash

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 85154729a09e39aa8d563ebcd3fcf71f379bf293..9bb227a63d50518abda7e36e80a387ffdc26612c 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -93,7 +93,7 @@ public:
 // ============================================================================
 
 
 // ============================================================================
 
 

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

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


@@ -154,7 +154,7 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 
 
 
 
 
 

-/** @ingroup group_funcmacro_env */
+/** @addtogroup group_funcmacro_env */

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


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


@@ -205,7 +221,7 @@ bool wxUnsetEnv(const wxString& var);
 
 
 
 
 
 

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

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


@@ -366,9 +382,15 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
     a busy cursor is shown while the browser is being launched (using
     wxBusyCursor).
 
     a busy cursor is shown while the browser is being launched (using
     wxBusyCursor).
 

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


@@ -416,6 +438,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


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

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

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


@@ -538,7 +581,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


@@ -641,11 +684,28 @@ 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 */

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


@@ -720,9 +780,7 @@ 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,


@@ -730,7 +788,7 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
 
 //@}
 
 
 //@}
 

-/** @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*),


@@ -755,6 +813,10 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}
          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,
                 wxProcess* callback = NULL);
 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
                 wxProcess* callback = NULL);


@@ -762,7 +824,7 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
                 wxProcess* callback = NULL);
 //@}
 
                 wxProcess* callback = NULL);
 //@}
 

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

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


@@ -779,15 +841,20 @@ 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()
 
     @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);
 


@@ -796,7 +863,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


@@ -806,15 +874,20 @@ 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()
 
     @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,
                 wxArrayString& errors, int flags = 0);
 */
 long wxExecute(const wxString& command, wxArrayString& output,
                 wxArrayString& errors, int flags = 0);


@@ -919,7 +992,7 @@ bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
 
 
 
 
 
 

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

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