// Name: utils.h
// 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);
/**
Constructs a busy cursor object, calling wxBeginBusyCursor().
*/
- wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+ wxBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);
/**
Destroys the busy cursor object, calling wxEndBusyCursor().
-/**
- @class wxMouseState
-
- Represents the mouse state.
-
- The methods of this class generally mirror the corresponding methods of
- wxMouseEvent.
-
- This class is implemented entirely in @<wx/utils.h@>, meaning no extra
- library needs to be linked to use this class.
-
- @category{misc}
-
- @see wxGetMouseState()
- */
-class wxMouseState
-{
-public:
- /**
- Default constructor.
- */
- wxMouseState();
-
- /**
- Returns X coordinate of the physical mouse event position.
- */
- wxCoord GetX() const;
- /**
- Returns Y coordinate of the physical mouse event position.
- */
- wxCoord GetY() const;
- /**
- Returns the physical mouse position.
- */
- wxPoint GetPosition() const;
-
- /**
- Returns @true if the left mouse button changed to down.
- */
- bool LeftDown() const;
- /**
- Returns @true if the middle mouse button changed to down.
- */
- bool MiddleDown() const;
- /**
- Returns @true if the right mouse button changed to down.
- */
- bool RightDown() const;
- /**
- Returns @true if the first extra button mouse button changed to down.
- */
- bool Aux1Down() const;
- /**
- Returns @true if the second extra button mouse button changed to down.
- */
- bool Aux2Down() const;
-
- /**
- Returns @true if the control key is down.
- */
- bool ControlDown() const;
- /**
- Returns @true if the shift key is down.
- */
- bool ShiftDown() const;
- /**
- Returns @true if the alt key is down.
- */
- bool AltDown() const;
- /**
- Returns @true if the meta key is down.
- */
- bool MetaDown() const;
- /**
- Same as MetaDown() under Mac systems, ControlDown() for the others.
- */
- bool CmdDown() const;
-};
-
-
// ============================================================================
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */
//@{
/**
@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
@note This function is categorized as a GUI one and so is not thread-safe.
@header{wx/utils.h}
+
+ @library{wxcore}
*/
void wxBell();
@since 2.9.0
+ @see wxGetLibraryVersionInfo()
+
@header{wx/utils.h}
*/
-void wxInfoMessageBox(wxWindow parent = NULL);
+void wxInfoMessageBox(wxWindow* parent);
//@}
+/** @addtogroup group_funcmacro_version */
+//@{
+/**
+ Get wxWidgets version information.
-/** @ingroup group_funcmacro_env */
+ @since 2.9.2
+
+ @see wxVersionInfo
+
+ @header{wx/utils.h}
+
+ @library{wxcore}
+*/
+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);
//@}
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
Find the deepest window at the given mouse position in screen coordinates,
returning the window if found, or @NULL if not.
+ This function takes child windows at the given position into account even
+ if they are disabled. The hidden children are however skipped by it.
+
@header{wx/utils.h}
*/
wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
@header{wx/utils.h}
*/
-long wxNewId();
+int wxNewId();
/**
Ensures that Ids subsequently generated by wxNewId() do not clash with the
@header{wx/utils.h}
*/
-void wxRegisterId(long id);
+void wxRegisterId(int id);
+
+/**
+ Opens the @a document in the application associated with the files of this
+ type.
+
+ The @a flags parameter is currently not used
+
+ Returns @true if the application was successfully launched.
+
+ @see wxLaunchDefaultBrowser(), wxExecute()
+
+ @header{wx/utils.h}
+*/
+bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
/**
- Opens the @a url in user's default browser. If the @a flags parameter
- contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
- (currently this is only supported under Windows). 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.
+ Opens the @a url in user's default browser.
+
+ If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
+ window is opened for the URL (currently this is only supported under
+ Windows).
+
+ And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
+ a busy cursor is shown while the browser is being launched (using
+ wxBusyCursor).
+
+ 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.
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);
/**
- Loads a user-defined Windows resource as a string. If the resource is
- found, the function creates a new character array and copies the data into
- it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
+ Loads an object from Windows resource file.
- The resource must be defined in the @c .rc file using the following syntax:
+ This function loads the resource with the given name and type from the
+ resources embedded into a Windows application.
+ The typical use for it is to load some data from the data files embedded
+ into the program itself. For example, you could have the following fragment
+ in your @c .rc file
+ @code
+ mydata MYDATA "myfile.dat"
+ @endcode
+ and then use it in the following way:
@code
- myResource TEXT file.ext
+ const void* data = NULL;
+ size_t size = 0;
+ if ( !wxLoadUserResource(&data, &size, "mydata", "MYDATA") ) {
+ ... handle error ...
+ }
+ else {
+ // Use the data in any way, for example:
+ wxMemoryInputStream is(data, size);
+ ... read the data from stream ...
+ }
@endcode
- Where @c file.ext is a file that the resource compiler can find.
+ @param outData Filled with the pointer to the data on successful return.
+ Notice that this pointer does @em not need to be freed by the caller.
+ @param outLen Filled with the length of the data in bytes.
+ @param resourceName The name of the resource to load.
+ @param resourceType The type of the resource in usual Windows format, i.e.
+ either a real string like "MYDATA" or an integer created by the
+ standard Windows @c MAKEINTRESOURCE() macro, including any constants
+ for the standard resources types like @c RT_RCDATA.
+ @param module The @c HINSTANCE of the module to load the resources from.
+ The current module is used by default.
+ @return true if the data was loaded from resource or false if it couldn't
+ be found (in which case no error is logged) or was found but couldn't
+ be loaded (which is unexpected and does result in an error message).
+
+ This function is available under Windows only.
+
+ @library{wxbase}
+
+ @header{wx/utils.h}
+
+ @since 2.9.1
+ */
+bool
+wxLoadUserResource(const void **outData,
+ size_t *outLen,
+ const wxString& resourceName,
+ const wxChar* resourceType = "TEXT",
+ WXHINSTANCE module = 0);
+
+/**
+ Loads a user-defined Windows resource as a string.
+
+ This is a wrapper for the general purpose overload wxLoadUserResource(const
+ void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be
+ more convenient for the string data, but does an extra copy compared to the
+ general version.
+
+ @param resourceName The name of the resource to load.
+ @param resourceType The type of the resource in usual Windows format, i.e.
+ either a real string like "MYDATA" or an integer created by the
+ standard Windows @c MAKEINTRESOURCE() macro, including any constants
+ for the standard resources types like @c RT_RCDATA.
+ @param pLen Filled with the length of the returned buffer if it is
+ non-@NULL. This parameter should be used if NUL characters can occur in
+ the resource data. It is new since wxWidgets 2.9.1
+ @param module The @c HINSTANCE of the module to load the resources from.
+ The current module is used by default. This parameter is new since
+ wxWidgets 2.9.1.
+ @return A pointer to the data to be <tt>delete[]</tt>d by caller on success
+ or @NULL on error.
This function is available under Windows only.
+ @library{wxbase}
+
@header{wx/utils.h}
*/
-wxString wxLoadUserResource(const wxString& resourceName,
- const wxString& resourceType = "TEXT");
+char* wxLoadUserResource(const wxString& resourceName,
+ const wxChar* resourceType = "TEXT",
+ int* pLen = NULL,
+ WXHINSTANCE module = 0);
/**
@deprecated Replaced by wxWindow::Close(). See the
*/
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.
By default, the functions strips both the mnemonics character (@c '&')
which is used to indicate a keyboard shortkey, and the accelerators, which
are used only in the menu items and are separated from the main text by the
- @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
+ @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
@c wxStrip_Accel to strip only the former or the latter part, respectively.
Notice that in most cases wxMenuItem::GetLabelFromText() or
-/** @ingroup group_funcmacro_networkuseros */
+/** @addtogroup group_funcmacro_networkuseros */
//@{
/**
@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
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();
+
//@}
-/** @ingroup 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;
+};
+
+/**
+ 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
+ @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);
//@}
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
//@{
/**
This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
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);
//@}
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
//@{
/**
@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
- 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
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
- 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 wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
both Unix and Windows but all the other signals are equivalent to
- @c wxSIGTERM under Windows.
+ @c wxSIGTERM under Windows. Moreover, under Windows, @c wxSIGTERM is
+ implemented by posting a message to the application window, so it only
+ works if the application does have windows. If it doesn't, as is notably
+ always the case for the console applications, you need to use @c wxSIGKILL
+ to actually kill the process. Of course, this doesn't allow the process to
+ shut down gracefully and so should be avoided if possible.
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
the @a flags.
- @note Doing this requires the corresponding access rights (superuser under
- Unix, SE_SHUTDOWN privilege under Windows NT) and that this function
- is only implemented under Unix and Win32.
+ @note Note that performing the shutdown requires the corresponding access
+ rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT)
+ and that this function is only implemented under Unix and MSW.
@param flags
- Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT
+ One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
+ @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
+ combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by
+ forcefully terminating all the applications. As doing this can result
+ in a data loss, this flag shouldn't be used unless really necessary.
@return @true on success, @false if an error occurred.
@header{wx/utils.h}
*/
-bool wxShutdown(wxShutdownFlags flags);
+bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
//@}
-/** @ingroup group_funcmacro_time */
+/** @addtogroup group_funcmacro_time */
//@{
/**
projects / wxWidgets.git / blobdiff