don't place NULL pointers in the GDK window array in GTKGetWindow()

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 1254434a7b0395bd66056a8a3008728f07cf39c4..534b610ea66dee07b33cefe800b4918e51392fbe 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 */
 //@{
 
 /**
@@ -205,7 +205,7 @@ bool wxUnsetEnv(const wxString& var);
 
 
 
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
 //@{
 
 /**
@@ -349,9 +349,11 @@ void wxRegisterId(long id);
 
     Returns @true if the application was successfully launched.
 
+    @see wxLaunchDefaultBrowser(), wxExecute()
+
     @header{wx/utils.h}
 */
-bool wxLaunchDefaultApplication(const wxString& document, int flags = 0)
+bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
 
 /**
     Opens the @a url in user's default browser.
@@ -364,9 +366,15 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0)
     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.
 
@@ -375,6 +383,8 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0)
           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);
@@ -412,6 +422,27 @@ wxString wxLoadUserResource(const wxString& resourceName,
 */
 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
@@ -444,7 +475,7 @@ wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
 
 
 
-/** @ingroup group_funcmacro_networkuseros */
+/** @addtogroup group_funcmacro_networkuseros */
 //@{
 
 /**
@@ -534,7 +565,7 @@ wxString wxGetFullHostName();
 
     @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
@@ -641,7 +672,7 @@ bool wxIsPlatformLittleEndian();
 
 
 
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
 //@{
 
 /**
@@ -710,7 +741,8 @@ bool wxIsPlatformLittleEndian();
     @param callback
         An optional pointer to wxProcess.
 
-    @see wxShell(), wxProcess, @ref page_samples_exec
+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 
     @header{wx/utils.h}
 
@@ -725,7 +757,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*),
@@ -746,6 +778,9 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
     @param callback
         An optional pointer to wxProcess.
 
+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
+
     @header{wx/utils.h}
 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
@@ -754,7 +789,7 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
                 wxProcess* callback = NULL);
 //@}
 
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
 //@{
 
 /**
@@ -768,16 +803,20 @@ 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 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.
 
+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
+
     @header{wx/utils.h}
 */
-long wxExecute(const wxString& command, wxArrayString& output,
-                int flags = 0);
+long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
@@ -789,12 +828,19 @@ long wxExecute(const wxString& command, wxArrayString& output,
     @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
         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.
 
+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
+
     @header{wx/utils.h}
 */
 long wxExecute(const wxString& command, wxArrayString& output,
@@ -900,7 +946,7 @@ bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
 
 
 
-/** @ingroup group_funcmacro_time */
+/** @addtogroup group_funcmacro_time */
 //@{
 
 /**