X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ea11aeeef0218fd58aeb2e141c57115716784c82..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/utils.h diff --git a/interface/wx/utils.h b/interface/wx/utils.h index 534b610ea6..120ed37cc3 100644 --- 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$ -// 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. + + 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); @@ -106,7 +114,7 @@ public: @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 @@ -145,10 +153,25 @@ void wxBell(); 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} + @library{wxcore} */ -void wxInfoMessageBox(wxWindow parent = NULL); +wxVersionInfo wxGetLibraryVersionInfo(); //@} @@ -157,6 +180,18 @@ void wxInfoMessageBox(wxWindow parent = NULL); /** @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. @@ -169,8 +204,9 @@ void wxInfoMessageBox(wxWindow parent = NULL); 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. @@ -180,10 +216,25 @@ wxChar* wxGetenv(const wxString& var); 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 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 value + New value of the variable. + @return + @true on success or @false if changing the value failed. @see wxUnsetEnv() @@ -192,8 +243,9 @@ bool wxGetEnv(const wxString& var, 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. @@ -201,6 +253,22 @@ bool wxSetEnv(const wxString& var, const wxString& value); */ 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); //@} @@ -633,8 +701,34 @@ bool wxGetUserName(char* buf, int sz); 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{Windows OS name, Major version, Minor version} + @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 MSDN + for more info about the values above. @see wxGetOsDescription(), wxPlatformInfo @@ -668,6 +762,23 @@ bool wxIsPlatform64Bit(); */ 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 + Linux Standard Base Core 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(); + //@} @@ -675,6 +786,36 @@ bool wxIsPlatformLittleEndian(); /** @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. @@ -740,6 +881,10 @@ bool wxIsPlatformLittleEndian(); 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() @@ -747,14 +892,12 @@ bool wxIsPlatformLittleEndian(); @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, - wxProcess* callback = NULL); - + wxProcess* callback = NULL, + const wxExecuteEnv* env = NULL); //@} /** @addtogroup group_funcmacro_procctrl */ @@ -777,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. + @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} + + @beginWxPerlOnly + In wxPerl this function is called @c Wx::ExecuteArgs. + @endWxPerlOnly */ 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, - wxProcess* callback = NULL); + wxProcess* callback = NULL, + const wxExecuteEnv *env = NULL); //@} /** @addtogroup group_funcmacro_procctrl */ @@ -806,24 +959,35 @@ 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 - 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 - their combination, in wxEXEC_SYNC case. + 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} + + @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*), 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 @@ -833,18 +997,28 @@ 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 - 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 - their combination, in wxEXEC_SYNC case. + 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} + + @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); + wxArrayString& errors, int flags = 0, + const wxExecuteEnv *env = NULL); /** Returns the number uniquely identifying the current process in the system. @@ -856,7 +1030,9 @@ unsigned long wxGetProcessId(); /** 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 @@ -885,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, - 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 @@ -908,8 +1084,8 @@ unsigned long wxGetProcessId(); @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 @@ -919,7 +1095,7 @@ int wxKill(long pid, int sig = wxSIGTERM, @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