Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index d8a7bdd01c78116ae1bc061cfa9e31080fe4bb2e..120ed37cc3a119f8c7af7602a04f5e4ffe0249dc 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

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


@@ -37,6 +37,14 @@ public:
     /**
         Disables all top level windows of the applications with the exception
         of @a winToSkip if it is not @NULL.
     /**
         Disables all top level windows of the applications with the exception
         of @a winToSkip if it is not @NULL.

+
+        Notice that under MSW if @a winToSkip appears in the taskbar, the user
+        will be able to close the entire application (even though its main
+        window is disabled) by right clicking on the taskbar icon and selecting
+        the appropriate "Close" command from the context menu. To prevent this
+        from happening you may want to use wxFRAME_TOOL_WINDOW, if applicable,
+        or wxFRAME_NO_TASKBAR style when creating the window that will remain
+        enabled.

     */
     wxWindowDisabler(wxWindow* winToSkip);
 
     */
     wxWindowDisabler(wxWindow* winToSkip);
 


@@ -106,7 +114,7 @@ public:
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+void wxBeginBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);

 
 /**
     Changes the cursor back to the original cursor, for all windows in the
 
 /**
     Changes the cursor back to the original cursor, for all windows in the


@@ -145,10 +153,25 @@ void wxBell();
     doesn't otherwise handle this event.
 
     @since 2.9.0
     doesn't otherwise handle this event.
 
     @since 2.9.0

+    @see wxGetLibraryVersionInfo()
+    @header{wx/utils.h}
+*/
+void wxInfoMessageBox(wxWindow* parent);
+
+//@}
+
+/** @addtogroup group_funcmacro_version */
+//@{

 
 

+/**
+    Get wxWidgets version information.
+
+    @since 2.9.2
+    @see wxVersionInfo

     @header{wx/utils.h}
     @header{wx/utils.h}

+    @library{wxcore}

 */
 */

-void wxInfoMessageBox(wxWindow parent = NULL);
+wxVersionInfo wxGetLibraryVersionInfo();

 
 //@}
 
 
 //@}
 


@@ -157,6 +180,18 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 /** @addtogroup group_funcmacro_env */
 //@{
 
 /** @addtogroup group_funcmacro_env */
 //@{
 

+/**
+    A map type containing environment variables names and values.
+
+    This type is used with wxGetEnvMap() function and wxExecuteEnv structure
+    optionally passed to wxExecute().
+
+    @since 2.9.2
+
+    @header{wx/utils.h}
+*/
+typedef wxStringToStringHashMap wxEnvVariableHashMap;
+

 /**
     This is a macro defined as @c getenv() or its wide char version in Unicode
     mode.
 /**
     This is a macro defined as @c getenv() or its wide char version in Unicode
     mode.


@@ -190,8 +225,9 @@ bool wxGetEnv(const wxString& var, wxString* value);
     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
     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.
+    compilers/CRT implementations (currently only MSVC and MinGW which uses the
+    same MSVC CRT) 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 var
         The environment variable to be set, must not contain @c '=' character.


@@ -217,6 +253,22 @@ bool wxSetEnv(const wxString& var, const wxString& value);
 */
 bool wxUnsetEnv(const wxString& var);
 
 */
 bool wxUnsetEnv(const wxString& var);
 

+/**
+    Fill a map with the complete content of current environment.
+
+    The map will contain the environment variable names as keys and their
+    values as values.
+
+    @param map
+        The environment map to fill, must be non-@NULL.
+    @return
+        @true if environment was successfully retrieved or @false otherwise.
+
+    @header{wx/utils.h}
+
+    @since 2.9.2
+*/
+bool wxGetEnvMap(wxEnvVariableHashMap *map);

 //@}
 
 
 //@}
 
 


@@ -649,8 +701,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 "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
 


@@ -684,6 +762,23 @@ 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();
+

 //@}
 
 
 //@}
 
 


@@ -691,6 +786,36 @@ bool wxIsPlatformLittleEndian();
 /** @addtogroup group_funcmacro_procctrl */
 //@{
 
 /** @addtogroup group_funcmacro_procctrl */
 //@{
 

+/**
+    @struct wxExecuteEnv
+
+    This structure can optionally be passed to wxExecute() to specify
+    additional options to use for the child process.
+
+    @since 2.9.2
+
+    @header{wx/utils.h}
+*/
+struct wxExecuteEnv
+{
+    /**
+        The initial working directory for the new process.
+
+        If this field is empty, the current working directory of this process
+        is used.
+    */
+    wxString cwd;
+
+    /**
+        The environment variable map.
+
+        If the map is empty, the environment variables of the current process
+        are also used for the child one, otherwise only the variables defined
+        in this map are used.
+    */
+    wxEnvVariableHashMap env;
+};
+

 /**
     Executes another program in Unix or Windows.
 
 /**
     Executes another program in Unix or Windows.
 


@@ -756,6 +881,10 @@ bool wxIsPlatformLittleEndian();
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

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


@@ -763,14 +892,12 @@ 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,

-                wxProcess* callback = NULL);
-
+                wxProcess* callback = NULL,
+                const wxExecuteEnv* env = NULL);

 //@}
 
 /** @addtogroup group_funcmacro_procctrl */
 //@}
 
 /** @addtogroup group_funcmacro_procctrl */


@@ -793,16 +920,26 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.
         their combination, in wxEXEC_SYNC case.
     @param callback
         An optional pointer to wxProcess.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @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
+    In wxPerl this function is called @c Wx::ExecuteArgs.
+    @endWxPerlOnly

 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
 */
 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,

-                wxProcess* callback = NULL);
+                wxProcess* callback = NULL,
+                const wxExecuteEnv *env = NULL);

 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,

-                wxProcess* callback = NULL);
+                wxProcess* callback = NULL,
+                const wxExecuteEnv *env = NULL);

 //@}
 
 /** @addtogroup group_funcmacro_procctrl */
 //@}
 
 /** @addtogroup group_funcmacro_procctrl */


@@ -825,13 +962,24 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
         May 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. wxEXEC_SYNC is always implicitly added to the flags.
         May 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. wxEXEC_SYNC is always implicitly added to the flags.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @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,
+                const wxExecuteEnv *env = NULL);

 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
 
 /**
     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),


@@ -852,14 +1000,25 @@ long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
         May 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. wxEXEC_SYNC is always implicitly added to the flags.
         May 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. wxEXEC_SYNC is always implicitly added to the flags.

+    @param env
+        An optional pointer to additional parameters for the child process,
+        such as its initial working directory and environment variables. This
+        parameter is available in wxWidgets 2.9.2 and later only.

 
     @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,
 */
 long wxExecute(const wxString& command, wxArrayString& output,

-                wxArrayString& errors, int flags = 0);
+                wxArrayString& errors, int flags = 0,
+                const wxExecuteEnv *env = NULL);

 
 /**
     Returns the number uniquely identifying the current process in the system.
 
 /**
     Returns the number uniquely identifying the current process in the system.


@@ -871,7 +1030,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


@@ -900,7 +1061,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


@@ -923,8 +1084,8 @@ unsigned long wxGetProcessId();
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-int wxKill(long pid, int sig = wxSIGTERM,
-            wxKillError rc = NULL, int flags = 0);
+int wxKill(long pid, wxSignal sig = wxSIGTERM,
+            wxKillError* rc = NULL, int flags = wxKILL_NOCHILDREN);

 
 /**
     Executes a command in an interactive shell window. If no command is
 
 /**
     Executes a command in an interactive shell window. If no command is


@@ -934,7 +1095,7 @@ int wxKill(long pid, int sig = wxSIGTERM,
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxShell(const wxString& command = NULL);
+bool wxShell(const wxString& command = wxEmptyString);

 
 /**
     This function shuts down or reboots the computer depending on the value of
 
 /**
     This function shuts down or reboots the computer depending on the value of