X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1058f652031c9b99daa7c701f09f16c3af7159c1..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/utils.h diff --git a/interface/wx/utils.h b/interface/wx/utils.h index 9bb227a63d..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); @@ -106,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 @@ -134,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(); @@ -146,9 +205,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 +236,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. @@ -190,8 +281,9 @@ bool wxGetEnv(const wxString& var, wxString* value); 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 so using wxGetenv() - (notice the difference in case) may not return the updated value. + 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. @@ -217,6 +309,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); //@} @@ -297,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); @@ -347,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 @@ -355,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 @@ -406,24 +517,92 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0); 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 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 @@ -444,19 +623,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); /** @@ -471,6 +650,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. @@ -649,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 @@ -708,6 +929,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. @@ -739,18 +1069,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 @@ -768,11 +1102,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() @@ -784,8 +1122,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 */ @@ -802,12 +1140,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() @@ -819,9 +1158,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 */ @@ -841,9 +1182,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() @@ -856,7 +1199,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*), @@ -874,9 +1218,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() @@ -890,7 +1236,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. @@ -902,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 @@ -928,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 @@ -954,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 @@ -965,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