X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1b2f7b6d75886325b818d46b8c6250b4d6431ccc..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/utils.h diff --git a/interface/wx/utils.h b/interface/wx/utils.h index c09df344ba..a7eae5dfd8 100644 --- a/interface/wx/utils.h +++ b/interface/wx/utils.h @@ -6,6 +6,56 @@ // 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 +87,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 +164,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 @@ -134,6 +192,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(); @@ -146,9 +206,29 @@ void wxBell(); @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 +237,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. @@ -218,6 +310,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); //@} @@ -298,6 +406,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); @@ -445,19 +556,19 @@ void wxPostDelete(wxObject* object); @header{wx/utils.h} */ -extern "C" -{ -typedef int (wxCMPFUNC_CONV *CMPFUNCDATA)(const void* pItem1, const void* pItem2, const void* user_data); -} +typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data); /** - Function for performing a qsort operation including a user data - parameter. + 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 *const pbase, size_t total_elems, - size_t size, CMPFUNCDATA cmp, const void* user_data); +void wxQsort(void* pbase, size_t total_elems, + size_t size, wxSortCallback cmp, const void* user_data); /** @@ -472,6 +583,22 @@ void wxQsort(void *const pbase, size_t total_elems, */ 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. @@ -660,7 +787,7 @@ wxString wxGetOsDescription(); '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 and "6" if the machine + 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 @@ -735,6 +862,115 @@ 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. @@ -766,18 +1002,22 @@ wxLinuxDistributionInfo wxGetLinuxDistributionInfo(); 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 @@ -795,11 +1035,15 @@ wxLinuxDistributionInfo wxGetLinuxDistributionInfo(); 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() @@ -811,8 +1055,8 @@ wxLinuxDistributionInfo wxGetLinuxDistributionInfo(); @endWxPerlOnly */ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); - + wxProcess* callback = NULL, + const wxExecuteEnv* env = NULL); //@} /** @addtogroup group_funcmacro_procctrl */ @@ -829,12 +1073,13 @@ 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() @@ -846,9 +1091,11 @@ long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, @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 */ @@ -868,9 +1115,11 @@ 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 - May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination. wxEXEC_SYNC is always implicitly added to the flags. + 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() @@ -883,7 +1132,8 @@ long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC, 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*), @@ -901,9 +1151,11 @@ 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 - May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination. wxEXEC_SYNC is always implicitly added to the flags. + 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() @@ -917,7 +1169,8 @@ long wxExecute(const wxString& command, wxArrayString& output, int flags = 0); @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. @@ -983,8 +1236,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 @@ -994,7 +1247,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