X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1ba0de2efa0a7d5bdb2fa69befe7f4c8c17ab291..cde80c9284b64d611e8cf4a7565de40aa0acce81:/interface/utils.h diff --git a/interface/utils.h b/interface/utils.h index 67e68ccad5..41ca90a8b4 100644 --- a/interface/utils.h +++ b/interface/utils.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: utils.h -// Purpose: interface of wxWindowDisabler +// Purpose: interface of various utility classes and functions // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,13 +10,15 @@ @class wxWindowDisabler @wxheader{utils.h} - This class disables all windows of the application (may be with the exception - of one of them) in its constructor and enables them back in its destructor. - This comes in handy when you want to indicate to the user that the application + This class disables all windows of the application (may be with the + exception of one of them) in its constructor and enables them back in its + destructor. + + This is useful when you want to indicate to the user that the application is currently busy and cannot respond to user input. @library{wxcore} - @category{FIXME} + @category{misc} @see wxBusyCursor */ @@ -24,13 +26,23 @@ class wxWindowDisabler { public: /** - Disables all top level windows of the applications with the exception of - @a winToSkip if it is not @NULL. + Disables all top level windows of the applications. + + If @a disable is @c false nothing is done. This can be convenient if + the windows should be disabled depending on some condition. + + @since 2.9.0 + */ + wxWindowDisabler(bool disable = true); + + /** + Disables all top level windows of the applications with the exception + of @a winToSkip if it is not @NULL. */ - wxWindowDisabler(wxWindow* winToSkip = NULL); + wxWindowDisabler(wxWindow* winToSkip); /** - Reenables back the windows disabled by the constructor. + Reenables the windows disabled by the constructor. */ ~wxWindowDisabler(); }; @@ -41,24 +53,24 @@ public: @class wxBusyCursor @wxheader{utils.h} - This class makes it easy to tell your user that the program is temporarily busy. - Just create a wxBusyCursor object on the stack, and within the current scope, - the hourglass will be shown. + This class makes it easy to tell your user that the program is temporarily + busy. Just create a wxBusyCursor object on the stack, and within the + current scope, the hourglass will be shown. For example: @code wxBusyCursor wait; - for (int i = 0; i 100000; i++) + for (int i = 0; i < 100000; i++) DoACalculation(); @endcode - It works by calling wxBeginBusyCursor() in the constructor, - and wxEndBusyCursor() in the destructor. + It works by calling wxBeginBusyCursor() in the constructor, and + wxEndBusyCursor() in the destructor. @library{wxcore} - @category{FIXME} + @category{misc} @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler */ @@ -78,6 +90,87 @@ public: +/** + @class wxMouseState + @wxheader{utils.h} + + 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 // ============================================================================ @@ -134,7 +227,7 @@ void wxBell(); and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise handle this event. - @wxsince{2.9.0} + @since 2.9.0 @header{wx/utils.h} */ @@ -195,246 +288,296 @@ bool wxUnsetEnv(const wxString& var); +/** @ingroup group_funcmacro_misc */ +//@{ + /** - Returns the type of power source as one of @c wxPOWER_SOCKET, - @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. - @c wxPOWER_UNKNOWN is also the default on platforms where this + Returns battery state as one of @c wxBATTERY_NORMAL_STATE, + @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, + @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. + @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this feature is not implemented (currently everywhere but MS Windows). @header{wx/utils.h} */ +wxBatteryState wxGetBatteryState(); + +/** + Returns the type of power source as one of @c wxPOWER_SOCKET, + @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the + default on platforms where this feature is not implemented (currently + everywhere but MS Windows). + + @header{wx/utils.h} +*/ wxPowerType wxGetPowerType(); -//@{ /** - This function returns the "user id" also known as "login name" under Unix i.e. - something like "jsmith". It uniquely identifies the current user (on this - system). - Under Windows or NT, this function first looks in the environment - variables USER and LOGNAME; if neither of these is found, the entry @b UserId - in the @b wxWidgets section of the WIN.INI file is tried. - The first variant of this function returns the login name if successful or an - empty string otherwise. The second (deprecated) function returns @true - if successful, @false otherwise. + Under X only, returns the current display name. - @see wxGetUserName() + @see wxSetDisplayName() @header{wx/utils.h} */ -wxString wxGetUserId(); -bool wxGetUserId(char* buf, int sz); -//@} +wxString wxGetDisplayName(); /** - @b NB: This function is now obsolete, please use - wxLogFatalError() instead. - Displays @a msg and exits. This writes to standard error under Unix, - and pops up a message box under Windows. Used for fatal internal - wxWidgets errors. See also wxError(). + For normal keys, returns @true if the specified key is currently down. + + For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if + the key is toggled such that its LED indicator is lit. There is currently + no way to test whether togglable keys are up or down. + + Even though there are virtual key codes defined for mouse buttons, they + cannot be used with this function currently. @header{wx/utils.h} */ -void wxFatalError(const wxString& msg, - const wxString& title = "wxWidgets Fatal Error"); +bool wxGetKeyState(wxKeyCode key); /** - Returns battery state as one of @c wxBATTERY_NORMAL_STATE, - @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, - @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. - @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where - this feature is not implemented (currently everywhere but MS Windows). + Returns the mouse position in screen coordinates. @header{wx/utils.h} */ -wxBatteryState wxGetBatteryState(); +wxPoint wxGetMousePosition(); /** - @b NB: This function is obsolete, please use - wxWindow::FindWindowByName instead. - Find a window by its name (as given in a window constructor or @b Create - function call). - If @a parent is @NULL, the search will start from all top-level - frames and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. - If no such named window is found, @b wxFindWindowByLabel is called. + Returns the current state of the mouse. Returns a wxMouseState instance + that contains the current position of the mouse pointer in screen + coordinates, as well as boolean values indicating the up/down status of the + mouse buttons and the modifier keys. @header{wx/utils.h} */ -wxWindow* wxFindWindowByName(const wxString& name, - wxWindow* parent = NULL); +wxMouseState wxGetMouseState(); /** - This function is deprecated as the ids generated by it can conflict with the - ids defined by the user code, use @c wxID_ANY to assign ids which are - guaranteed to not conflict with the user-defined ids for the controls and menu - items you create instead of using this function. + This function enables or disables all top level windows. It is used by + wxSafeYield(). - Generates an integer identifier unique to this run of the program. + @header{wx/utils.h} +*/ +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. @header{wx/utils.h} */ -long wxNewId(); +wxWindow* wxFindWindowAtPoint(const wxPoint& pt); /** - Ensures that ids subsequently generated by @b NewId do not clash with - the given @b id. + @deprecated Replaced by wxWindow::FindWindowByLabel(). + + Find a window by its label. Depending on the type of window, the label may + be a window title or panel item label. If @a parent is @NULL, the search + will start from all top-level frames and dialog boxes; if non-@NULL, the + search will be limited to the given window hierarchy. The search is + recursive in both cases. @header{wx/utils.h} */ -void wxRegisterId(long id); +wxWindow* wxFindWindowByLabel(const wxString& label, + wxWindow* parent = NULL); /** - @b NB: This function is now obsolete, replaced by Log - functions() and wxLogDebug() in particular. - Display a debugging message; under Windows, this will appear on the - debugger command window, and under Unix, it will be written to standard - error. - The syntax is identical to @b printf: pass a format string and a - variable list of arguments. - @b Tip: under Windows, if your application crashes before the - message appears in the debugging window, put a wxYield call after - each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s - (at least for Watcom C++): preformat your messages and use OutputDebugString - instead. + @deprecated Replaced by wxWindow::FindWindowByName(). + + Find a window by its name (as given in a window constructor or @e Create + function call). If @a parent is @NULL, the search will start from all + top-level frames and dialog boxes; if non-@NULL, the search will be limited + to the given window hierarchy. The search is recursive in both cases. + + If no such named window is found, wxFindWindowByLabel() is called. @header{wx/utils.h} */ -void wxDebugMsg(const wxString& fmt, ... ); +wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL); /** - For normal keys, returns @true if the specified key is currently down. - For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns - @true if the key is toggled such that its LED indicator is lit. There is - currently no way to test whether togglable keys are up or down. - Even though there are virtual key codes defined for mouse buttons, they - cannot be used with this function currently. + Find a menu item identifier associated with the given frame's menu bar. @header{wx/utils.h} */ -bool wxGetKeyState(wxKeyCode key); +int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, + const wxString& itemString); /** - Returns the string containing the description of the current platform in a - user-readable form. For example, this function may return strings like - @c Windows NT Version 4.0 or @c Linux 2.2.2 i386. + @deprecated Ids generated by it can conflict with the Ids defined by the + user code, use @c wxID_ANY to assign ids which are guaranteed + to not conflict with the user-defined ids for the controls and + menu items you create instead of using this function. - @see ::wxGetOsVersion + Generates an integer identifier unique to this run of the program. @header{wx/utils.h} */ -wxString wxGetOsDescription(); +long wxNewId(); /** - Return the (current) user's home directory. + Ensures that Ids subsequently generated by wxNewId() do not clash with the + given @a id. - @see wxGetUserHome(), wxStandardPaths + @header{wx/utils.h} +*/ +void wxRegisterId(long id); + +/** + 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. + + Returns @true if the application was successfully launched. + + @note For some configurations of the running user, the application which is + launched to open the given URL may be URL-dependent (e.g. a browser + may be used for local URLs while another one may be used for remote + URLs). @header{wx/utils.h} */ -wxString wxGetHomeDir(); +bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); /** - Sleeps for the specified number of milliseconds. Notice that usage of this - function is encouraged instead of calling usleep(3) directly because the - standard usleep() function is not MT safe. + 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. + + The resource must be defined in the @c .rc file using the following syntax: + + @code + myResource TEXT file.ext + @endcode + + Where @c file.ext is a file that the resource compiler can find. + + This function is available under Windows only. @header{wx/utils.h} */ -void wxMilliSleep(unsigned long milliseconds); +wxString wxLoadUserResource(const wxString& resourceName, + const wxString& resourceType = "TEXT"); /** - Sleeps for the specified number of microseconds. The microsecond resolution may - not, in fact, be available on all platforms (currently only Unix platforms with - nanosleep(2) may provide it) in which case this is the same as - wxMilliSleep()(@e microseconds/1000). + @deprecated Replaced by wxWindow::Close(). See the + @ref overview_windowdeletion "window deletion overview". + + Tells the system to delete the specified object when all other events have + been processed. In some environments, it is necessary to use this instead + of deleting a frame directly with the delete operator, because some GUIs + will still send events to a deleted window. @header{wx/utils.h} */ -void wxMicroSleep(unsigned long microseconds); +void wxPostDelete(wxObject* object); + +/** + 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 + should be used for creating windows from this point on. Setting the display + within an application allows multiple displays to be used. + @see wxGetDisplayName() + + @header{wx/utils.h} +*/ +void wxSetDisplayName(const wxString& displayName); /** - Find a menu item identifier associated with the given frame's menu bar. + 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 wxStrip_Accel to strip only the former or the latter part, respectively. + + Notice that in most cases wxMenuItem::GetLabelFromText() or + wxControl::GetLabelText() can be used instead. @header{wx/utils.h} */ -int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, - const wxString& itemString); +wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); + +//@} + + + +/** @ingroup group_funcmacro_networkuseros */ +//@{ /** - This function enables or disables all top level windows. It is used by - ::wxSafeYield. + Copies the user's email address into the supplied buffer, by concatenating + the values returned by wxGetFullHostName() and wxGetUserId(). + + @return @true if successful, @false otherwise. @header{wx/utils.h} */ -void wxEnableTopLevelWindows(bool enable = true); +wxString wxGetEmailAddress(); /** - 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 wxStrip_Accel to strip only the former - or the latter part, respectively. - Notice that in most cases - wxMenuItem::GetLabelFromText or - wxControl::GetLabelText can be used instead. + @deprecated Use wxGetEmailAddress() instead. + + @param buf Buffer to store the email address in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. @header{wx/utils.h} */ -wxString wxStripMenuCodes(const wxString& str, - int flags = wxStrip_All); +bool wxGetEmailAddress(char* buf, int sz); /** - @b NB: This function is now obsolete, please use wxLogError() - instead. - Displays @a msg and continues. This writes to standard error under - Unix, and pops up a message box under Windows. Used for internal - wxWidgets errors. See also wxFatalError(). + Returns the amount of free memory in bytes under environments which support + it, and -1 if not supported or failed to perform measurement. @header{wx/utils.h} */ -void wxError(const wxString& msg, - const wxString& title = "wxWidgets Internal Error"); +wxMemorySize wxGetFreeMemory(); /** - Open the @a url in user's default browser. If @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 @c file:// prefix), if it doesn't - correspond to an existing file and the URL has no scheme @c http:// is - prepended to it by default. - Returns @true if the application was successfully launched. - Note that for some configurations of the running user, the application which - is launched to open the given URL may be URL-dependent (e.g. a browser may be - used for - local URLs while another one may be used for remote URLs). + Return the (current) user's home directory. + + @see wxGetUserHome(), wxStandardPaths @header{wx/utils.h} */ -bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); +wxString wxGetHomeDir(); /** - Executes a command in an interactive shell window. If no command is - specified, then just the shell is spawned. - See also wxExecute(), @ref overview_sampleexec "Exec sample". + Copies the current host machine's name into the supplied buffer. Please + note that the returned name is @e not fully qualified, i.e. it does not + include the domain name. + + Under Windows or NT, this function first looks in the environment variable + SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets + section of the WIN.INI file is tried. + + @return The hostname if successful or an empty string otherwise. + + @see wxGetFullHostName() @header{wx/utils.h} */ -bool wxShell(const wxString& command = NULL); +wxString wxGetHostName(); /** - Gets the version and the operating system ID for currently running OS. - See wxPlatformInfo for more details about wxOperatingSystemId. + @deprecated Use wxGetHostName() instead. + + @param buf Buffer to store the host name in. + @param sz Size of the buffer. - @see ::wxGetOsDescription, wxPlatformInfo + @return @true if successful, @false otherwise. @header{wx/utils.h} */ -wxOperatingSystemId wxGetOsVersion(int* major = NULL, - int* minor = NULL); +bool wxGetHostName(char* buf, int sz); /** Returns the FQDN (fully qualified domain host name) or an empty string on @@ -447,217 +590,279 @@ wxOperatingSystemId wxGetOsVersion(int* major = NULL, wxString wxGetFullHostName(); /** - Tells the system to delete the specified object when - all other events have been processed. In some environments, it is - necessary to use this instead of deleting a frame directly with the - delete operator, because some GUIs will still send events to a deleted window. - Now obsolete: use wxWindow::Close instead. + Returns the home directory for the given user. If the @a user is empty + (default value), this function behaves like wxGetHomeDir() (i.e. returns + the current user home directory). + + If the home directory couldn't be determined, an empty string is returned. @header{wx/utils.h} */ -void wxPostDelete(wxObject* object); +wxString wxGetUserHome(const wxString& user = ""); /** - @b NB: This function is obsolete, please use - wxWindow::FindWindowByLabel instead. - Find a window by its label. Depending on the type of window, the label may be a - window title - or panel item label. If @a parent is @NULL, the search will start from all - top-level - frames and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. + This function returns the "user id" also known as "login name" under Unix + (i.e. something like "jsmith"). It uniquely identifies the current user (on + this system). Under Windows or NT, this function first looks in the + environment variables USER and LOGNAME; if neither of these is found, the + entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried. + + @return The login name if successful or an empty string otherwise. + + @see wxGetUserName() @header{wx/utils.h} */ -wxWindow* wxFindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); +wxString wxGetUserId(); + +/** + @deprecated Use wxGetUserId() instead. + + @param buf Buffer to store the login name in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. + @header{wx/utils.h} +*/ +bool wxGetUserId(char* buf, int sz); /** - Returns the mouse position in screen coordinates. + This function returns the full user name (something like "Mr. John Smith"). + + Under Windows or NT, this function looks for the entry UserName in the + wxWidgets section of the WIN.INI file. If PenWindows is running, the entry + Current in the section User of the PENWIN.INI file is used. + + @return The full user name if successful or an empty string otherwise. + + @see wxGetUserId() @header{wx/utils.h} */ -wxPoint wxGetMousePosition(); +wxString wxGetUserName(); /** - 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. - The resource must be defined in the @c .rc file using the following syntax: + @deprecated Use wxGetUserName() instead. - @code - myResource TEXT file.ext - @endcode + @param buf Buffer to store the full user name in. + @param sz Size of the buffer. - where @c file.ext is a file that the resource compiler can find. - This function is available under Windows only. + @return @true if successful, @false otherwise. @header{wx/utils.h} */ -wxString wxLoadUserResource(const wxString& resourceName, - const wxString& resourceType = "TEXT"); +bool wxGetUserName(char* buf, int sz); /** - Returns the amount of free memory in bytes under environments which - support it, and -1 if not supported or failed to perform measurement. + Returns the string containing the description of the current platform in a + user-readable form. For example, this function may return strings like + "Windows NT Version 4.0" or "Linux 2.2.2 i386". + + @see wxGetOsVersion() + + @header{wx/utils.h} */ -wxMemorySize wxGetFreeMemory(); +wxString wxGetOsDescription(); -//@{ /** - Copies the current host machine's name into the supplied buffer. Please note - that the returned name is @e not fully qualified, i.e. it does not include - the domain name. - Under Windows or NT, this function first looks in the environment - variable SYSTEM_NAME; if this is not found, the entry @b HostName - in the @b wxWidgets section of the WIN.INI file is tried. - The first variant of this function returns the hostname if successful or an - empty string otherwise. The second (deprecated) function returns @true - if successful, @false otherwise. + Gets the version and the operating system ID for currently running OS. See + wxPlatformInfo for more details about wxOperatingSystemId. - @see wxGetFullHostName() + @see wxGetOsDescription(), wxPlatformInfo @header{wx/utils.h} */ -wxString wxGetHostName(); -bool wxGetHostName(char* buf, int sz); -//@} +wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL); /** - Under X only, returns the current display name. See also wxSetDisplayName(). + Returns @true if the operating system the program is running under is 64 + bit. The check is performed at run-time and may differ from the value + available at compile-time (at compile-time you can just check if + sizeof(void*) == 8) since the program could be running in + emulation mode or in a mixed 32/64 bit system (bi-architecture operating + system). + + @note This function is not 100% reliable on some systems given the fact + that there isn't always a standard way to do a reliable check on the + OS architecture. @header{wx/utils.h} */ -wxString wxGetDisplayName(); +bool wxIsPlatform64Bit(); /** - Returns the home directory for the given user. If the @a user is empty - (default value), this function behaves like - wxGetHomeDir() i.e. returns the current user home - directory. - If the home directory couldn't be determined, an empty string is returned. + Returns @true if the current platform is little endian (instead of big + endian). The check is performed at run-time. + + @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros" @header{wx/utils.h} */ -wxString wxGetUserHome(const wxString& user = ""); +bool wxIsPlatformLittleEndian(); + +//@} + + +/** @ingroup group_funcmacro_procctrl */ //@{ + /** - @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr - and it only takes the @c command argument, - and returns a 3-element list @c ( status, output, errors ), where - @c output and @c errors are array references. Executes another program in Unix or Windows. - The first form takes a command string, such as @c "emacs file.txt". - The second form takes an array of values: a command, any number of - arguments, terminated by @NULL. - The semantics of the third and fourth versions is different from the first two - and is described in more details below. - If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow - of control immediately returns. If it contains @c wxEXEC_SYNC, the current - application waits until the other program has terminated. + + In the overloaded versions of this function, if @a flags parameter contains + @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If + it contains @c wxEXEC_SYNC, the current application waits until the other + program has terminated. + In the case of synchronous execution, the return value is the exit code of - the process (which terminates by the moment the function returns) and will be - -1 if the process couldn't be started and typically 0 if the process - terminated successfully. Also, while waiting for the process to - terminate, wxExecute will call wxYield(). Because of this, by - default this function disables all application windows to avoid unexpected - reentrancies which could result from the users interaction with the program - while the child process is running. If you are sure that it is safe to not - disable the program windows, you may pass @c wxEXEC_NODISABLE flag to - prevent this automatic disabling from happening. + the process (which terminates by the moment the function returns) and will + be -1 if the process couldn't be started and typically 0 if the process + terminated successfully. Also, while waiting for the process to terminate, + wxExecute() will call wxYield(). Because of this, by default this function + disables all application windows to avoid unexpected reentrancies which + could result from the users interaction with the program while the child + process is running. If you are sure that it is safe to not disable the + program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this + automatic disabling from happening. + For asynchronous execution, however, the return value is the process id and zero value indicates that the command could not be executed. As an added complication, the return value of -1 in this case indicates that we didn't - launch a new process, but connected to the running one (this can only happen in - case of using DDE under Windows for command execution). In particular, in this, - and only this, case the calling code will not get the notification about + launch a new process, but connected to the running one (this can only + happen when using DDE under Windows for command execution). In particular, + in this case only, the calling code will not get the notification about process termination. - If callback isn't @NULL and if execution is asynchronous, - 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 + + If @a callback isn't @NULL and if execution is asynchronous, + 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. - 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). + happening, i.e. with this flag the child process window will be shown + normally. + + 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). + 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 short-lived processes as otherwise the application windows risk becoming - unresponsive from the users point of view. As this flag only makes sense with - @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags - is provided as a convenience. - Finally, you may use the third overloaded version of this function to execute - a process (always synchronously, the contents of @a flags is or'd with - @c wxEXEC_SYNC) and capture its output in the array @e output. The - fourth version adds the possibility to additionally capture the messages from - standard error output in the @a errors array. - @b NB: Currently wxExecute() can only be used from the main thread, calling - this function from another thread will result in an assert failure in debug - build and won't work. + unresponsive from the users point of view. As this flag only makes sense + with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these + flags is provided as a convenience. + + @note Currently wxExecute() can only be used from the main thread, calling + this function from another thread will result in an assert failure in + debug build and won't work. @param command - The command to execute and any parameters to pass to it as a - single string. + The command to execute and any parameters to pass to it as a single + 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. + @param callback + An optional pointer to wxProcess. + + @see wxShell(), wxProcess, @ref page_samples_exec + + @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. + @endWxPerlOnly +*/ +long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); + +//@} + +/** @ingroup group_funcmacro_procctrl */ +//@{ +/** + This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), + please see its documentation for general information. + + This version takes an array of values: a command, any number of arguments, + terminated by @NULL. + @param argv - The command to execute should be the first element of this - array, any additional ones are the command parameters and the array must be + The command to execute should be the first element of this array, any + additional ones are the command parameters and the array must be terminated with a @NULL pointer. @param flags - Combination of bit masks wxEXEC_ASYNC, - wxEXEC_SYNC and wxEXEC_NOHIDE + 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. @param callback - An optional pointer to wxProcess - - @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample". + An optional pointer to wxProcess. @header{wx/utils.h} */ -long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, +long wxExecute(char** argv, int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); +long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC, wxProcess* callback = NULL); -wxPerl note: long wxExecute(char** argv, - int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); -wxPerl note: long wxExecute(const wxString& command, - wxArrayString& output, - int flags = 0); -wxPerl note: long wxExecute(const wxString& command, - wxArrayString& output, - wxArrayString& errors, - int flags = 0); //@} +/** @ingroup group_funcmacro_procctrl */ +//@{ + /** - Returns a string representing the current date and time. + This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), + please see its documentation for general information. + + This version can be used to execute a process (always synchronously, the + contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in + the array @e output. + + @param command + The command to execute and any parameters to pass to it as a single + string. + @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. @header{wx/utils.h} */ -wxString wxNow(); +long wxExecute(const wxString& command, wxArrayString& output, + int flags = 0); /** - Returns @true if the operating system the program is running under is 64 bit. - The check is performed at run-time and may differ from the value available at - compile-time (at compile-time you can just check if @c sizeof(void*)==8) - since the program could be running in emulation mode or in a mixed 32/64 bit - system - (bi-architecture operating system). - Very important: this function is not 100% reliable on some systems given the - fact - that there isn't always a standard way to do a reliable check on the OS - architecture. + 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. + + @param command + The command to execute and any parameters to pass to it as a single + string. + @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. @header{wx/utils.h} */ -bool wxIsPlatform64Bit(); +long wxExecute(const wxString& command, wxArrayString& output, + wxArrayString& errors, int flags = 0); /** Returns the number uniquely identifying the current process in the system. @@ -669,12 +874,12 @@ unsigned long wxGetProcessId(); /** Equivalent to the Unix kill function: send the given signal @a sig to the - process with PID @e pid. The valid signal values are + process with PID @a pid. The valid signal values are: @code enum wxSignal { - wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGNONE = 0, // verify if the process exists under Unix wxSIGHUP, wxSIGINT, wxSIGQUIT, @@ -683,98 +888,125 @@ unsigned long wxGetProcessId(); wxSIGABRT, wxSIGEMT, wxSIGFPE, - wxSIGKILL, // forcefully kill, dangerous! + wxSIGKILL, // forcefully kill, dangerous! wxSIGBUS, wxSIGSEGV, wxSIGSYS, wxSIGPIPE, wxSIGALRM, - wxSIGTERM // terminate the process gently + wxSIGTERM // terminate the process gently }; @endcode - @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 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. - Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will - be filled with an element of @c wxKillError enum: + + 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: @code 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 + 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 }; @endcode - The @a flags parameter can be wxKILL_NOCHILDREN (the default), - or wxKILL_CHILDREN, in which case the child processes of this - process will be killed too. Note that under Unix, for wxKILL_CHILDREN - to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER - to wxExecute. + The @a flags parameter can be wxKILL_NOCHILDREN (the default), or + wxKILL_CHILDREN, in which case the child processes of this process will be + killed too. Note that under Unix, for wxKILL_CHILDREN to work you should + have created the process by passing wxEXEC_MAKE_GROUP_LEADER to + wxExecute(). + + @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec + + @header{wx/utils.h} +*/ +int wxKill(long pid, int sig = wxSIGTERM, + wxKillError rc = NULL, int flags = 0); + +/** + Executes a command in an interactive shell window. If no command is + specified, then just the shell is spawned. - @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" + @see wxExecute(), @ref page_samples_exec @header{wx/utils.h} */ -int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL, - int flags = 0); +bool wxShell(const wxString& command = NULL); /** - Returns the current state of the mouse. Returns a wxMouseState - instance that contains the current position of the mouse pointer in - screen coordinates, as well as boolean values indicating the up/down - status of the mouse buttons and the modifier keys. + 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. + + @param flags + Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT + + @return @true on success, @false if an error occurred. @header{wx/utils.h} */ -wxMouseState wxGetMouseState(); +bool wxShutdown(wxShutdownFlags flags); + +//@} + + +/** @ingroup group_funcmacro_time */ //@{ + /** - Copies the user's email address into the supplied buffer, by - concatenating the values returned by wxGetFullHostName() - and wxGetUserId(). - Returns @true if successful, @false otherwise. + Sleeps for the specified number of microseconds. The microsecond resolution + may not, in fact, be available on all platforms (currently only Unix + platforms with nanosleep(2) may provide it) in which case this is the same + as calling wxMilliSleep() with the argument of @e microseconds/1000. @header{wx/utils.h} */ -wxString wxGetEmailAddress(); -bool wxGetEmailAddress(char* buf, int sz); -//@} +void wxMicroSleep(unsigned long microseconds); /** - Sleeps for the specified number of seconds. + Sleeps for the specified number of milliseconds. Notice that usage of this + function is encouraged instead of calling usleep(3) directly because the + standard @e usleep() function is not MT safe. @header{wx/utils.h} */ -void wxSleep(int secs); +void wxMilliSleep(unsigned long milliseconds); /** - Returns @true if the current platform is little endian (instead of big - endian). - The check is performed at run-time. + Returns a string representing the current date and time. + + @header{wx/utils.h} +*/ +wxString wxNow(); - @see @ref overview_byteordermacros "Byte order macros" +/** + Sleeps for the specified number of seconds. @header{wx/utils.h} */ -bool wxIsPlatformLittleEndian(); +void wxSleep(int secs); /** - 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 should be used for - creating - windows from this point on. Setting the display within an application allows - multiple - displays to be used. - See also wxGetDisplayName(). + @deprecated This function is deprecated because its name is misleading: + notice that the argument is in milliseconds, not microseconds. + Please use either wxMilliSleep() or wxMicroSleep() depending on + the resolution you need. + + Sleeps for the specified number of milliseconds. @header{wx/utils.h} */ -void wxSetDisplayName(const wxString& displayName); +void wxUsleep(unsigned long milliseconds); + +//@}