Return wxFONTFAMILY_DEFAULT, not UNKNOWN, from wxFont::GetFamily().

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 1254434a7b0395bd66056a8a3008728f07cf39c4..8bf3b1948f25d474cf8db634077361ac9efe5866 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


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

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


@@ -349,9 +365,11 @@ void wxRegisterId(long id);
 
     Returns @true if the application was successfully launched.
 
 
     Returns @true if the application was successfully launched.
 

+    @see wxLaunchDefaultBrowser(), wxExecute()
+

     @header{wx/utils.h}
 */
     @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.
 
 /**
     Opens the @a url in user's default browser.


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


@@ -375,6 +399,8 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0)
           may be used for local URLs while another one may be used for remote
           URLs).
 
           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);
     @header{wx/utils.h}
 */
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);


@@ -412,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


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

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

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


@@ -534,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


@@ -602,8 +649,34 @@ bool wxGetUserName(char* buf, int sz);
 wxString wxGetOsDescription();
 
 /**
 wxString wxGetOsDescription();
 
 /**

-    Gets the version and the operating system ID for currently running OS. See
-    wxPlatformInfo for more details about wxOperatingSystemId.
+    Gets the version and the operating system ID for currently running OS. 
+    The returned wxOperatingSystemId value can be used for a basic categorization
+    of the OS family; the major and minor version numbers allows to detect a specific
+    system.
+    
+    For Unix-like systems (@c wxOS_UNIX) the major and minor version integers will 
+    contain the kernel major and minor version numbers (as returned by the
+    'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.
+
+    For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the
+    natural version numbers associated with the OS; e.g. "10" and and "6" if the machine
+    is using Mac OS X Snow Leopard.    
+    
+    For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will 
+    contain the following values:
+    @beginTable
+    @row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>}
+    @row3col{Windows 7,                 6, 1}
+    @row3col{Windows Server 2008 R2,    6, 1}
+    @row3col{Windows Server 2008,       6, 0}
+    @row3col{Windows Vista,             6, 0}
+    @row3col{Windows Server 2003 R2,    5, 2}
+    @row3col{Windows Server 2003,       5, 2}
+    @row3col{Windows XP,                5, 1}
+    @row3col{Windows 2000,              5, 0}
+    @endDefList
+    See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a>
+    for more info about the values above.

 
     @see wxGetOsDescription(), wxPlatformInfo
 
 
     @see wxGetOsDescription(), wxPlatformInfo
 


@@ -637,11 +710,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 */

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


@@ -710,14 +800,13 @@ bool wxIsPlatformLittleEndian();
     @param callback
         An optional pointer to wxProcess.
 
     @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}
 
     @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,


@@ -725,7 +814,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*),


@@ -746,7 +835,14 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
     @param callback
         An optional pointer to wxProcess.
 
     @param callback
         An optional pointer to wxProcess.
 

+    @see wxShell(), wxProcess, @ref page_samples_exec,
+         wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
+

     @header{wx/utils.h}
     @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);


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

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

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


@@ -768,34 +864,56 @@ 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 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
     @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}
 
     @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);

 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
     please see its documentation for general information.
 
     This version adds the possibility to additionally capture the messages from
 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
     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
         string.
 
     @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
     @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}
 
     @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);


@@ -810,7 +928,9 @@ unsigned long wxGetProcessId();
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the

-    process with PID @a pid. The valid signal values are:
+    process with PID @a pid.
+
+    The valid signal values are:

 
     @code
     enum wxSignal
 
     @code
     enum wxSignal


@@ -839,7 +959,7 @@ unsigned long wxGetProcessId();
     @c wxSIGTERM under Windows.
 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
     @c wxSIGTERM under Windows.
 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,

-    it will be filled with a value of the the @c wxKillError enum:
+    it will be filled with a value from the @c wxKillError enum:

 
     @code
     enum wxKillError
 
     @code
     enum wxKillError


@@ -900,7 +1020,7 @@ bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
 
 
 
 
 
 

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

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