// Purpose: interface of various utility classes and functions
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+/**
+ Signal constants used by wxProcess.
+*/
+enum wxSignal
+{
+ wxSIGNONE = 0, //!< verify if the process exists under Unix
+ wxSIGHUP,
+ wxSIGINT,
+ wxSIGQUIT,
+ wxSIGILL,
+ wxSIGTRAP,
+ wxSIGABRT,
+ wxSIGEMT,
+ wxSIGFPE,
+ wxSIGKILL, //!< forcefully kill, dangerous!
+ wxSIGBUS,
+ wxSIGSEGV,
+ wxSIGSYS,
+ wxSIGPIPE,
+ wxSIGALRM,
+ wxSIGTERM //!< terminate the process gently
+};
+
+/**
+ Return values for wxProcess::Kill.
+*/
+enum wxKillError
+{
+ wxKILL_OK, //!< no error
+ wxKILL_BAD_SIGNAL, //!< no such signal
+ wxKILL_ACCESS_DENIED, //!< permission denied
+ wxKILL_NO_PROCESS, //!< no such process
+ wxKILL_ERROR //!< another, unspecified error
+};
+
+enum wxKillFlags
+{
+ wxKILL_NOCHILDREN = 0, //!< don't kill children
+ wxKILL_CHILDREN = 1 //!< kill children
+};
+
+enum wxShutdownFlags
+{
+ wxSHUTDOWN_FORCE = 1, //!< can be combined with other flags (MSW-only)
+ wxSHUTDOWN_POWEROFF = 2, //!< power off the computer
+ wxSHUTDOWN_REBOOT = 4, //!< shutdown and reboot
+ wxSHUTDOWN_LOGOFF = 8 //!< close session (currently MSW-only)
+};
+
+
/**
@class wxWindowDisabler
/**
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);
@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
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();
//@}
/** @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.
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.
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()
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.
*/
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);
//@}
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.
*/
void wxPostDelete(wxObject* object);
+
+/**
+ Compare function type for use with wxQsort()
+
+ @header{wx/utils.h}
+*/
+typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data);
+
+/**
+ Function implementing quick sort algorithm.
+
+ This function sorts @a total_elems objects of size @a size located at @a
+ pbase. It uses @a cmp function for comparing them and passes @a user_data
+ pointer to the comparison function each time it's called.
+
+ @header{wx/utils.h}
+*/
+void wxQsort(void* pbase, size_t total_elems,
+ size_t size, wxSortCallback 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
*/
void wxSetDisplayName(const wxString& displayName);
+
+/**
+ flags for wxStripMenuCodes
+*/
+enum
+{
+ // strip '&' characters
+ wxStrip_Mnemonics = 1,
+
+ // strip everything after '\t'
+ wxStrip_Accel = 2,
+
+ // strip everything (this is the default)
+ wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
+};
+
/**
Strips any menu codes from @a str and returns the result.
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
*/
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();
+
//@}
/** @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;
+};
+
+/**
+ Bit flags that can be used with wxExecute().
+ */
+enum
+{
+ /**
+ Execute the process asynchronously.
+
+ Notice that, due to its value, this is the default.
+ */
+ wxEXEC_ASYNC = 0,
+
+ /**
+ Execute the process synchronously.
+ */
+ wxEXEC_SYNC = 1,
+
+ /**
+ Always show the child process console under MSW.
+
+ The child console is hidden by default if the child IO is redirected,
+ this flag allows to change this and show it nevertheless.
+
+ This flag is ignored under the other platforms.
+ */
+ wxEXEC_SHOW_CONSOLE = 2,
+
+ /**
+ Make the new process a group leader.
+
+ Under Unix, if the process is the group leader then passing
+ wxKILL_CHILDREN to wxKill() kills all children as well as pid.
+
+ Under MSW, applies only to console applications and is only supported
+ under NT family (i.e. not under Windows 9x). It corresponds to the
+ native @c CREATE_NEW_PROCESS_GROUP and, in particular, ensures that
+ Ctrl-Break signals will be sent to all children of this process as well
+ to the process itself. Support for this flag under MSW was added in
+ version 2.9.4 of wxWidgets.
+ */
+ wxEXEC_MAKE_GROUP_LEADER = 4,
+
+ /**
+ Don't disable the program UI while running the child synchronously.
+
+ By default synchronous execution disables all program windows to avoid
+ that the user interacts with the program while the child process is
+ running, you can use this flag to prevent this from happening.
+
+ This flag can only be used with ::wxEXEC_SYNC.
+ */
+ wxEXEC_NODISABLE = 8,
+
+ /**
+ Don't dispatch events while the child process is executed.
+
+ By default, the event loop is run while waiting for synchronous
+ execution to complete and this flag can be used to simply block the
+ main process until the child process finishes
+
+ This flag can only be used with ::wxEXEC_SYNC.
+ */
+ wxEXEC_NOEVENTS = 16,
+
+ /**
+ Hide child process console under MSW.
+
+ Under MSW, hide the console of the child process if it has one,
+ even if its IO is not redirected.
+
+ This flag is ignored under the other platforms.
+ */
+ wxEXEC_HIDE_CONSOLE = 32,
+
+ /**
+ Convenient synonym for flags given system()-like behaviour.
+ */
+ wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
+};
/**
Executes another program in Unix or Windows.
wxProcess::OnTerminate() will be called when the process finishes.
Specifying this parameter also allows you to redirect the standard input
and/or output of the process being launched by calling
- wxProcess::Redirect(). If the child process IO is redirected, under Windows
- the process window is not shown by default (this avoids having to flush an
- unnecessary console for the processes which don't create any windows
- anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
- happening, i.e. with this flag the child process window will be shown
- normally.
+ wxProcess::Redirect().
+
+ Under Windows, when launching a console process its console is shown by
+ default but hidden if its IO is redirected. Both of these default
+ behaviours may be overridden: if ::wxEXEC_HIDE_CONSOLE is specified, the
+ console will never be shown. If ::wxEXEC_SHOW_CONSOLE is used, the console
+ will be shown even if the child process IO is redirected. Neither of these
+ flags affect non-console Windows applications or does anything under the
+ other systems.
Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
the new process is a group leader (this will create a new session if
needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
well as all of its children (except those which have started their own
- session).
+ session). Under MSW, this flag can be used with console processes only and
+ corresponds to the native @c CREATE_NEW_PROCESS_GROUP flag.
The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
place while the child process is running. It should be only used for very
string, i.e. "emacs file.txt".
@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.
+ wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, 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.
@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
- 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 */
additional ones are the command parameters and the array must be
terminated with a @NULL pointer.
@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.
+ Same as for wxExecute(const wxString&,int,wxProcess*) overload.
@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 */
@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.
+ Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
+ @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
@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.
+ Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
+ @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.
/**
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
@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
@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
@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
projects / wxWidgets.git / blobdiff