X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/118a41d993eaf5c14ad4a8d82c2fcb28c9630242..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/utils.h diff --git a/interface/wx/utils.h b/interface/wx/utils.h index d4b6d21b78..5573a19b93 100644 --- a/interface/wx/utils.h +++ b/interface/wx/utils.h @@ -2,10 +2,59 @@ // 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 @@ -37,6 +86,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); @@ -78,7 +135,7 @@ public: /** 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(). @@ -88,92 +145,12 @@ public: -/** - @class wxMouseState - - Represents the mouse state. - - The methods of this class generally mirror the corresponding methods of - wxMouseEvent. - - This class is implemented entirely in @, 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 */ //@{ /** @@ -186,7 +163,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 @@ -214,6 +191,8 @@ bool wxIsBusy(); @note This function is categorized as a GUI one and so is not thread-safe. @header{wx/utils.h} + + @library{wxcore} */ void wxBell(); @@ -226,17 +205,49 @@ 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. + + @since 2.9.2 + + @see wxVersionInfo + + @header{wx/utils.h} + + @library{wxcore} +*/ +wxVersionInfo wxGetLibraryVersionInfo(); + +//@} -/** @ingroup 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. @@ -249,8 +260,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. @@ -260,10 +272,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() @@ -272,8 +299,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. @@ -281,11 +309,27 @@ 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); //@} -/** @ingroup group_funcmacro_misc */ +/** @addtogroup group_funcmacro_misc */ //@{ /** @@ -361,6 +405,9 @@ void wxEnableTopLevelWindows(bool enable = true); 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); @@ -411,7 +458,7 @@ int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, @header{wx/utils.h} */ -long wxNewId(); +int wxNewId(); /** Ensures that Ids subsequently generated by wxNewId() do not clash with the @@ -419,7 +466,7 @@ long wxNewId(); @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 @@ -429,9 +476,11 @@ void wxRegisterId(long id); Returns @true if the application was successfully launched. + @see wxLaunchDefaultBrowser(), wxExecute() + @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. @@ -444,9 +493,15 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0) 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. @@ -455,29 +510,99 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0) 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 - myResource TEXT file.ext + mydata MYDATA "myfile.dat" @endcode + and then use it in the following way: + @code + 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 + + @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). - Where @c file.ext is a file that the resource compiler can find. + 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 delete[]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 @@ -492,6 +617,27 @@ wxString wxLoadUserResource(const wxString& resourceName, */ 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 @@ -504,13 +650,29 @@ void wxPostDelete(wxObject* object); */ 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 @@ -524,7 +686,7 @@ wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); -/** @ingroup group_funcmacro_networkuseros */ +/** @addtogroup group_funcmacro_networkuseros */ //@{ /** @@ -614,7 +776,7 @@ wxString wxGetFullHostName(); @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 @@ -682,8 +844,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 @@ -717,13 +905,139 @@ 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(); + //@} -/** @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. @@ -755,18 +1069,22 @@ bool wxIsPlatformLittleEndian(); 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 @@ -784,28 +1102,31 @@ bool wxIsPlatformLittleEndian(); 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*), @@ -819,22 +1140,32 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, 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 */ //@{ /** @@ -848,37 +1179,65 @@ 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 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. @@ -890,7 +1249,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 @@ -916,10 +1277,15 @@ unsigned long wxGetProcessId(); @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 @@ -942,8 +1308,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 @@ -953,7 +1319,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 @@ -980,7 +1346,7 @@ bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF); -/** @ingroup group_funcmacro_time */ +/** @addtogroup group_funcmacro_time */ //@{ /**