better document the possible arguments accepted by wxLaunchDefaultBrowser; in particular mention the 'mailto:' scheme

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59239 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/utils.h

@@ -366,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://"
+    The parameter @a url is interpreted as follows:
-    prefix), if it doesn't correspond to an existing file and the URL has no
+    - if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "mailto:")
-    scheme "http://" is prepended to it by default.
+      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.
 

src/common/utilscmn.cpp

@@ -1010,10 +1010,14 @@ static bool DoLaunchDefaultBrowserHelper(const wxString& urlOrig, int flags)
     //
     // for (int i=0; i<2; i++)
     // {
+    //   // test arguments without a valid URL scheme:
     //   wxLaunchDefaultBrowser("C:\\test.txt", i==0 ? 0 : wxBROWSER_NEW_WINDOW);
     //   wxLaunchDefaultBrowser("wxwidgets.org", i==0 ? 0 : wxBROWSER_NEW_WINDOW);
+    //
+    //   // test arguments with different valid schemes:
     //   wxLaunchDefaultBrowser("file:/C%3A/test.txt", i==0 ? 0 : wxBROWSER_NEW_WINDOW);
     //   wxLaunchDefaultBrowser("http://wxwidgets.org", i==0 ? 0 : wxBROWSER_NEW_WINDOW);
+    //   wxLaunchDefaultBrowser("mailto:user@host.org", i==0 ? 0 : wxBROWSER_NEW_WINDOW);
     // }
     // (assuming you have a C:\test.txt file)
 
@@ -1039,7 +1043,7 @@ static bool DoLaunchDefaultBrowserHelper(const wxString& urlOrig, int flags)
             // TODO: extract URLToFileName() to some always compiled in
             //       function
 #if wxUSE_FILESYSTEM
-            // ShellExecuteEx() doesn't like the "file" scheme when opening local files; 
+            // ShellExecuteEx() doesn't like the "file" scheme when opening local files;
             // remove it
             url = wxFileSystem::URLToFileName(url).GetFullPath();
 #endif // wxUSE_FILESYSTEM