1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of various utility classes and functions
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxWindowDisabler
12 This class disables all windows of the application (may be with the
13 exception of one of them) in its constructor and enables them back in its
16 This is useful when you want to indicate to the user that the application
17 is currently busy and cannot respond to user input.
24 class wxWindowDisabler
28 Disables all top level windows of the applications.
30 If @a disable is @c false nothing is done. This can be convenient if
31 the windows should be disabled depending on some condition.
35 wxWindowDisabler(bool disable
= true);
38 Disables all top level windows of the applications with the exception
39 of @a winToSkip if it is not @NULL.
41 wxWindowDisabler(wxWindow
* winToSkip
);
44 Reenables the windows disabled by the constructor.
54 This class makes it easy to tell your user that the program is temporarily
55 busy. Just create a wxBusyCursor object on the stack, and within the
56 current scope, the hourglass will be shown.
63 for (int i = 0; i < 100000; i++)
67 It works by calling wxBeginBusyCursor() in the constructor, and
68 wxEndBusyCursor() in the destructor.
73 @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
79 Constructs a busy cursor object, calling wxBeginBusyCursor().
81 wxBusyCursor(const wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
84 Destroys the busy cursor object, calling wxEndBusyCursor().
91 // ============================================================================
92 // Global functions/macros
93 // ============================================================================
96 /** @addtogroup group_funcmacro_dialog */
100 Changes the cursor to the given cursor for all windows in the application.
101 Use wxEndBusyCursor() to revert the cursor back to its previous state.
102 These two calls can be nested, and a counter ensures that only the outer
105 @see wxIsBusy(), wxBusyCursor
109 void wxBeginBusyCursor(const wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
112 Changes the cursor back to the original cursor, for all windows in the
113 application. Use with wxBeginBusyCursor().
115 @see wxIsBusy(), wxBusyCursor
119 void wxEndBusyCursor();
122 Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
132 Ring the system bell.
134 @note This function is categorized as a GUI one and so is not thread-safe.
141 Shows a message box with the information about the wxWidgets build used,
142 including its version, most important build parameters and the version of
143 the underlying GUI toolkit. This is mainly used for diagnostic purposes
144 and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
145 doesn't otherwise handle this event.
148 @see wxGetLibraryVersionInfo()
151 void wxInfoMessageBox(wxWindow
* parent
);
155 /** @addtogroup group_funcmacro_version */
159 Get wxWidgets version information.
166 wxVersionInfo
wxGetLibraryVersionInfo();
172 /** @addtogroup group_funcmacro_env */
176 A map type containing environment variables names and values.
178 This type is used with wxGetEnvMap() function and wxExecuteEnv structure
179 optionally passed to wxExecute().
185 typedef wxStringToStringHashMap wxEnvVariableHashMap
;
188 This is a macro defined as @c getenv() or its wide char version in Unicode
191 Note that under Win32 it may not return correct value for the variables set
192 with wxSetEnv(), use wxGetEnv() function instead.
196 wxChar
* wxGetenv(const wxString
& var
);
199 Returns the current value of the environment variable @a var in @a value.
201 @a value may be @NULL if you just want to know if the variable exists and
202 are not interested in its value.
204 Returns @true if the variable exists, @false otherwise.
208 bool wxGetEnv(const wxString
& var
, wxString
* value
);
211 Sets the value of the environment variable @a var (adding it if necessary)
214 Notice that under Windows platforms the program may have two different
215 environment blocks: the first one is that of a Windows process and is
216 always present, but the CRT may maintain its own independent copy of the
217 environment. wxSetEnv() will always update the first copy, which means that
218 wxGetEnv(), which uses it directly, will always return the expected value
219 after this call. But wxSetEnv() only updates the second copy for some
220 compilers/CRT implementations (currently only MSVC and MinGW which uses the
221 same MSVC CRT) and so using wxGetenv() (notice the difference in case) may
222 not return the updated value.
225 The environment variable to be set, must not contain @c '=' character.
227 New value of the variable.
229 @true on success or @false if changing the value failed.
235 bool wxSetEnv(const wxString
& var
, const wxString
& value
);
238 Removes the variable @a var from the environment.
240 wxGetEnv() will return @NULL after the call to this function.
242 Returns @true on success.
246 bool wxUnsetEnv(const wxString
& var
);
249 Fill a map with the complete content of current environment.
251 The map will contain the environment variable names as keys and their
255 The environment map to fill, must be non-@NULL.
257 @true if environment was successfully retrieved or @false otherwise.
263 bool wxGetEnvMap(wxEnvVariableHashMap
*map
);
268 /** @addtogroup group_funcmacro_misc */
272 Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
273 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
274 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
275 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
276 feature is not implemented (currently everywhere but MS Windows).
280 wxBatteryState
wxGetBatteryState();
283 Returns the type of power source as one of @c wxPOWER_SOCKET,
284 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
285 default on platforms where this feature is not implemented (currently
286 everywhere but MS Windows).
290 wxPowerType
wxGetPowerType();
293 Under X only, returns the current display name.
295 @see wxSetDisplayName()
299 wxString
wxGetDisplayName();
302 For normal keys, returns @true if the specified key is currently down.
304 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
305 the key is toggled such that its LED indicator is lit. There is currently
306 no way to test whether togglable keys are up or down.
308 Even though there are virtual key codes defined for mouse buttons, they
309 cannot be used with this function currently.
313 bool wxGetKeyState(wxKeyCode key
);
316 Returns the mouse position in screen coordinates.
320 wxPoint
wxGetMousePosition();
323 Returns the current state of the mouse. Returns a wxMouseState instance
324 that contains the current position of the mouse pointer in screen
325 coordinates, as well as boolean values indicating the up/down status of the
326 mouse buttons and the modifier keys.
330 wxMouseState
wxGetMouseState();
333 This function enables or disables all top level windows. It is used by
338 void wxEnableTopLevelWindows(bool enable
= true);
341 Find the deepest window at the given mouse position in screen coordinates,
342 returning the window if found, or @NULL if not.
346 wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
349 @deprecated Replaced by wxWindow::FindWindowByLabel().
351 Find a window by its label. Depending on the type of window, the label may
352 be a window title or panel item label. If @a parent is @NULL, the search
353 will start from all top-level frames and dialog boxes; if non-@NULL, the
354 search will be limited to the given window hierarchy. The search is
355 recursive in both cases.
359 wxWindow
* wxFindWindowByLabel(const wxString
& label
,
360 wxWindow
* parent
= NULL
);
363 @deprecated Replaced by wxWindow::FindWindowByName().
365 Find a window by its name (as given in a window constructor or @e Create
366 function call). If @a parent is @NULL, the search will start from all
367 top-level frames and dialog boxes; if non-@NULL, the search will be limited
368 to the given window hierarchy. The search is recursive in both cases.
370 If no such named window is found, wxFindWindowByLabel() is called.
374 wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
* parent
= NULL
);
377 Find a menu item identifier associated with the given frame's menu bar.
381 int wxFindMenuItemId(wxFrame
* frame
, const wxString
& menuString
,
382 const wxString
& itemString
);
385 @deprecated Ids generated by it can conflict with the Ids defined by the
386 user code, use @c wxID_ANY to assign ids which are guaranteed
387 to not conflict with the user-defined ids for the controls and
388 menu items you create instead of using this function.
390 Generates an integer identifier unique to this run of the program.
397 Ensures that Ids subsequently generated by wxNewId() do not clash with the
402 void wxRegisterId(long id
);
405 Opens the @a document in the application associated with the files of this
408 The @a flags parameter is currently not used
410 Returns @true if the application was successfully launched.
412 @see wxLaunchDefaultBrowser(), wxExecute()
416 bool wxLaunchDefaultApplication(const wxString
& document
, int flags
= 0);
419 Opens the @a url in user's default browser.
421 If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
422 window is opened for the URL (currently this is only supported under
425 And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
426 a busy cursor is shown while the browser is being launched (using
429 The parameter @a url is interpreted as follows:
430 - if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "mailto:")
431 it is passed to the appropriate browser configured in the user system.
432 - if it has no valid scheme (e.g. it's a local file path without the @c "file:"
433 prefix), then ::wxFileExists and ::wxDirExists are used to test if it's a
434 local file/directory; if it is, then the browser is called with the
435 @a url parameter eventually prefixed by @c "file:".
436 - if it has no valid scheme and it's not a local file/directory, then @c "http:"
437 is prepended and the browser is called.
439 Returns @true if the application was successfully launched.
441 @note For some configurations of the running user, the application which is
442 launched to open the given URL may be URL-dependent (e.g. a browser
443 may be used for local URLs while another one may be used for remote
446 @see wxLaunchDefaultApplication(), wxExecute()
450 bool wxLaunchDefaultBrowser(const wxString
& url
, int flags
= 0);
453 Loads a user-defined Windows resource as a string. If the resource is
454 found, the function creates a new character array and copies the data into
455 it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
457 The resource must be defined in the @c .rc file using the following syntax:
460 myResource TEXT file.ext
463 Where @c file.ext is a file that the resource compiler can find.
465 This function is available under Windows only.
469 wxString
wxLoadUserResource(const wxString
& resourceName
,
470 const wxString
& resourceType
= "TEXT");
473 @deprecated Replaced by wxWindow::Close(). See the
474 @ref overview_windowdeletion "window deletion overview".
476 Tells the system to delete the specified object when all other events have
477 been processed. In some environments, it is necessary to use this instead
478 of deleting a frame directly with the delete operator, because some GUIs
479 will still send events to a deleted window.
483 void wxPostDelete(wxObject
* object
);
487 Compare function type for use with wxQsort()
493 typedef int (wxCMPFUNC_CONV
*CMPFUNCDATA
)(const void* pItem1
, const void* pItem2
, const void* user_data
);
497 Function for performing a qsort operation including a user data
502 void wxQsort(void *const pbase
, size_t total_elems
,
503 size_t size
, CMPFUNCDATA cmp
, const void* user_data
);
507 Under X only, sets the current display name. This is the X host and display
508 name such as "colonsay:0.0", and the function indicates which display
509 should be used for creating windows from this point on. Setting the display
510 within an application allows multiple displays to be used.
512 @see wxGetDisplayName()
516 void wxSetDisplayName(const wxString
& displayName
);
519 Strips any menu codes from @a str and returns the result.
521 By default, the functions strips both the mnemonics character (@c '&')
522 which is used to indicate a keyboard shortkey, and the accelerators, which
523 are used only in the menu items and are separated from the main text by the
524 @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
525 @c wxStrip_Accel to strip only the former or the latter part, respectively.
527 Notice that in most cases wxMenuItem::GetLabelFromText() or
528 wxControl::GetLabelText() can be used instead.
532 wxString
wxStripMenuCodes(const wxString
& str
, int flags
= wxStrip_All
);
538 /** @addtogroup group_funcmacro_networkuseros */
542 Copies the user's email address into the supplied buffer, by concatenating
543 the values returned by wxGetFullHostName() and wxGetUserId().
545 @return @true if successful, @false otherwise.
549 wxString
wxGetEmailAddress();
552 @deprecated Use wxGetEmailAddress() instead.
554 @param buf Buffer to store the email address in.
555 @param sz Size of the buffer.
557 @return @true if successful, @false otherwise.
561 bool wxGetEmailAddress(char* buf
, int sz
);
564 Returns the amount of free memory in bytes under environments which support
565 it, and -1 if not supported or failed to perform measurement.
569 wxMemorySize
wxGetFreeMemory();
572 Return the (current) user's home directory.
574 @see wxGetUserHome(), wxStandardPaths
578 wxString
wxGetHomeDir();
581 Copies the current host machine's name into the supplied buffer. Please
582 note that the returned name is @e not fully qualified, i.e. it does not
583 include the domain name.
585 Under Windows or NT, this function first looks in the environment variable
586 SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
587 section of the WIN.INI file is tried.
589 @return The hostname if successful or an empty string otherwise.
591 @see wxGetFullHostName()
595 wxString
wxGetHostName();
598 @deprecated Use wxGetHostName() instead.
600 @param buf Buffer to store the host name in.
601 @param sz Size of the buffer.
603 @return @true if successful, @false otherwise.
607 bool wxGetHostName(char* buf
, int sz
);
610 Returns the FQDN (fully qualified domain host name) or an empty string on
617 wxString
wxGetFullHostName();
620 Returns the home directory for the given user. If the @a user is empty
621 (default value), this function behaves like wxGetHomeDir() (i.e. returns
622 the current user home directory).
624 If the home directory couldn't be determined, an empty string is returned.
628 wxString
wxGetUserHome(const wxString
& user
= wxEmptyString
);
631 This function returns the "user id" also known as "login name" under Unix
632 (i.e. something like "jsmith"). It uniquely identifies the current user (on
633 this system). Under Windows or NT, this function first looks in the
634 environment variables USER and LOGNAME; if neither of these is found, the
635 entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
637 @return The login name if successful or an empty string otherwise.
643 wxString
wxGetUserId();
646 @deprecated Use wxGetUserId() instead.
648 @param buf Buffer to store the login name in.
649 @param sz Size of the buffer.
651 @return @true if successful, @false otherwise.
655 bool wxGetUserId(char* buf
, int sz
);
658 This function returns the full user name (something like "Mr. John Smith").
660 Under Windows or NT, this function looks for the entry UserName in the
661 wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
662 Current in the section User of the PENWIN.INI file is used.
664 @return The full user name if successful or an empty string otherwise.
670 wxString
wxGetUserName();
673 @deprecated Use wxGetUserName() instead.
675 @param buf Buffer to store the full user name in.
676 @param sz Size of the buffer.
678 @return @true if successful, @false otherwise.
682 bool wxGetUserName(char* buf
, int sz
);
685 Returns the string containing the description of the current platform in a
686 user-readable form. For example, this function may return strings like
687 "Windows NT Version 4.0" or "Linux 2.2.2 i386".
689 @see wxGetOsVersion()
693 wxString
wxGetOsDescription();
696 Gets the version and the operating system ID for currently running OS.
697 The returned wxOperatingSystemId value can be used for a basic categorization
698 of the OS family; the major and minor version numbers allows to detect a specific
701 For Unix-like systems (@c wxOS_UNIX) the major and minor version integers will
702 contain the kernel major and minor version numbers (as returned by the
703 'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.
705 For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the
706 natural version numbers associated with the OS; e.g. "10" and and "6" if the machine
707 is using Mac OS X Snow Leopard.
709 For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will
710 contain the following values:
712 @row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>}
713 @row3col{Windows 7, 6, 1}
714 @row3col{Windows Server 2008 R2, 6, 1}
715 @row3col{Windows Server 2008, 6, 0}
716 @row3col{Windows Vista, 6, 0}
717 @row3col{Windows Server 2003 R2, 5, 2}
718 @row3col{Windows Server 2003, 5, 2}
719 @row3col{Windows XP, 5, 1}
720 @row3col{Windows 2000, 5, 0}
722 See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a>
723 for more info about the values above.
725 @see wxGetOsDescription(), wxPlatformInfo
729 wxOperatingSystemId
wxGetOsVersion(int* major
= NULL
, int* minor
= NULL
);
732 Returns @true if the operating system the program is running under is 64
733 bit. The check is performed at run-time and may differ from the value
734 available at compile-time (at compile-time you can just check if
735 <tt>sizeof(void*) == 8</tt>) since the program could be running in
736 emulation mode or in a mixed 32/64 bit system (bi-architecture operating
739 @note This function is not 100% reliable on some systems given the fact
740 that there isn't always a standard way to do a reliable check on the
745 bool wxIsPlatform64Bit();
748 Returns @true if the current platform is little endian (instead of big
749 endian). The check is performed at run-time.
751 @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"
755 bool wxIsPlatformLittleEndian();
758 Returns a structure containing informations about the currently running
761 This function uses the @c lsb_release utility which is part of the
762 <tt>Linux Standard Base Core</tt> specification
763 (see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB
764 release 1.0 (released in 2001).
765 The @c lsb_release utility is very common on modern Linux distributions but in
766 case it's not available, then this function will return a ::wxLinuxDistributionInfo
767 structure containing empty strings.
769 This function is Linux-specific and is only available when the @c __LINUX__
772 wxLinuxDistributionInfo
wxGetLinuxDistributionInfo();
778 /** @addtogroup group_funcmacro_procctrl */
784 This structure can optionally be passed to wxExecute() to specify
785 additional options to use for the child process.
794 The initial working directory for the new process.
796 If this field is empty, the current working directory of this process
802 The environment variable map.
804 If the map is empty, the environment variables of the current process
805 are also used for the child one, otherwise only the variables defined
806 in this map are used.
808 wxEnvVariableHashMap env
;
812 Executes another program in Unix or Windows.
814 In the overloaded versions of this function, if @a flags parameter contains
815 @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
816 it contains @c wxEXEC_SYNC, the current application waits until the other
817 program has terminated.
819 In the case of synchronous execution, the return value is the exit code of
820 the process (which terminates by the moment the function returns) and will
821 be -1 if the process couldn't be started and typically 0 if the process
822 terminated successfully. Also, while waiting for the process to terminate,
823 wxExecute() will call wxYield(). Because of this, by default this function
824 disables all application windows to avoid unexpected reentrancies which
825 could result from the users interaction with the program while the child
826 process is running. If you are sure that it is safe to not disable the
827 program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
828 automatic disabling from happening.
830 For asynchronous execution, however, the return value is the process id and
831 zero value indicates that the command could not be executed. As an added
832 complication, the return value of -1 in this case indicates that we didn't
833 launch a new process, but connected to the running one (this can only
834 happen when using DDE under Windows for command execution). In particular,
835 in this case only, the calling code will not get the notification about
838 If @a callback isn't @NULL and if execution is asynchronous,
839 wxProcess::OnTerminate() will be called when the process finishes.
840 Specifying this parameter also allows you to redirect the standard input
841 and/or output of the process being launched by calling
842 wxProcess::Redirect(). If the child process IO is redirected, under Windows
843 the process window is not shown by default (this avoids having to flush an
844 unnecessary console for the processes which don't create any windows
845 anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
846 happening, i.e. with this flag the child process window will be shown
849 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
850 the new process is a group leader (this will create a new session if
851 needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
852 well as all of its children (except those which have started their own
855 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
856 place while the child process is running. It should be only used for very
857 short-lived processes as otherwise the application windows risk becoming
858 unresponsive from the users point of view. As this flag only makes sense
859 with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
860 flags is provided as a convenience.
862 @note Currently wxExecute() can only be used from the main thread, calling
863 this function from another thread will result in an assert failure in
864 debug build and won't work.
867 The command to execute and any parameters to pass to it as a single
868 string, i.e. "emacs file.txt".
870 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
871 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
872 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
873 their combination, in wxEXEC_SYNC case.
875 An optional pointer to wxProcess.
877 An optional pointer to additional parameters for the child process,
878 such as its initial working directory and environment variables. This
879 parameter is available in wxWidgets 2.9.2 and later only.
881 @see wxShell(), wxProcess, @ref page_samples_exec,
882 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
887 In wxPerl this function is called @c Wx::ExecuteCommand.
890 long wxExecute(const wxString
& command
, int flags
= wxEXEC_ASYNC
,
891 wxProcess
* callback
= NULL
,
892 const wxExecuteEnv
* env
= NULL
);
895 /** @addtogroup group_funcmacro_procctrl */
898 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
899 please see its documentation for general information.
901 This version takes an array of values: a command, any number of arguments,
905 The command to execute should be the first element of this array, any
906 additional ones are the command parameters and the array must be
907 terminated with a @NULL pointer.
909 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
910 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
911 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
912 their combination, in wxEXEC_SYNC case.
914 An optional pointer to wxProcess.
916 An optional pointer to additional parameters for the child process,
917 such as its initial working directory and environment variables. This
918 parameter is available in wxWidgets 2.9.2 and later only.
920 @see wxShell(), wxProcess, @ref page_samples_exec,
921 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
926 In wxPerl this function is called @c Wx::ExecuteArgs.
929 long wxExecute(char** argv
, int flags
= wxEXEC_ASYNC
,
930 wxProcess
* callback
= NULL
,
931 const wxExecuteEnv
*env
= NULL
);
932 long wxExecute(wchar_t** argv
, int flags
= wxEXEC_ASYNC
,
933 wxProcess
* callback
= NULL
,
934 const wxExecuteEnv
*env
= NULL
);
937 /** @addtogroup group_funcmacro_procctrl */
941 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
942 please see its documentation for general information.
944 This version can be used to execute a process (always synchronously, the
945 contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
949 The command to execute and any parameters to pass to it as a single
952 The string array where the stdout of the executed process is saved.
954 May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
955 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
956 their combination. wxEXEC_SYNC is always implicitly added to the flags.
958 An optional pointer to additional parameters for the child process,
959 such as its initial working directory and environment variables. This
960 parameter is available in wxWidgets 2.9.2 and later only.
962 @see wxShell(), wxProcess, @ref page_samples_exec,
963 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
968 This function is called @c Wx::ExecuteStdout: it only takes the
969 @a command argument, and returns a 2-element list (@c status, @c output),
970 where @c output in an array reference.
973 long wxExecute(const wxString
& command
, wxArrayString
& output
, int flags
= 0,
974 const wxExecuteEnv
*env
= NULL
);
977 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
978 please see its documentation for general information.
980 This version adds the possibility to additionally capture the messages from
981 standard error output in the @a errors array. As with the above overload
982 capturing standard output only, execution is always synchronous.
985 The command to execute and any parameters to pass to it as a single
988 The string array where the stdout of the executed process is saved.
990 The string array where the stderr of the executed process is saved.
992 May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
993 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
994 their combination. wxEXEC_SYNC is always implicitly added to the flags.
996 An optional pointer to additional parameters for the child process,
997 such as its initial working directory and environment variables. This
998 parameter is available in wxWidgets 2.9.2 and later only.
1000 @see wxShell(), wxProcess, @ref page_samples_exec,
1001 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
1006 This function is called @c Wx::ExecuteStdoutStderr: it only takes the
1007 @a command argument, and returns a 3-element list (@c status, @c output,
1008 @c errors), where @c output and @c errors are array references.
1011 long wxExecute(const wxString
& command
, wxArrayString
& output
,
1012 wxArrayString
& errors
, int flags
= 0,
1013 const wxExecuteEnv
*env
= NULL
);
1016 Returns the number uniquely identifying the current process in the system.
1017 If an error occurs, 0 is returned.
1021 unsigned long wxGetProcessId();
1024 Equivalent to the Unix kill function: send the given signal @a sig to the
1025 process with PID @a pid.
1027 The valid signal values are:
1032 wxSIGNONE = 0, // verify if the process exists under Unix
1041 wxSIGKILL, // forcefully kill, dangerous!
1047 wxSIGTERM // terminate the process gently
1051 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
1052 both Unix and Windows but all the other signals are equivalent to
1053 @c wxSIGTERM under Windows.
1055 Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
1056 it will be filled with a value from the @c wxKillError enum:
1061 wxKILL_OK, // no error
1062 wxKILL_BAD_SIGNAL, // no such signal
1063 wxKILL_ACCESS_DENIED, // permission denied
1064 wxKILL_NO_PROCESS, // no such process
1065 wxKILL_ERROR // another, unspecified error
1069 The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
1070 wxKILL_CHILDREN, in which case the child processes of this process will be
1071 killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
1072 have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
1075 @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec
1079 int wxKill(long pid
, wxSignal sig
= wxSIGTERM
,
1080 wxKillError
* rc
= NULL
, int flags
= wxKILL_NOCHILDREN
);
1083 Executes a command in an interactive shell window. If no command is
1084 specified, then just the shell is spawned.
1086 @see wxExecute(), @ref page_samples_exec
1090 bool wxShell(const wxString
& command
= wxEmptyString
);
1093 This function shuts down or reboots the computer depending on the value of
1096 @note Note that performing the shutdown requires the corresponding access
1097 rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT)
1098 and that this function is only implemented under Unix and MSW.
1101 One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
1102 @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
1103 combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by
1104 forcefully terminating all the applications. As doing this can result
1105 in a data loss, this flag shouldn't be used unless really necessary.
1107 @return @true on success, @false if an error occurred.
1111 bool wxShutdown(int flags
= wxSHUTDOWN_POWEROFF
);
1117 /** @addtogroup group_funcmacro_time */
1121 Sleeps for the specified number of microseconds. The microsecond resolution
1122 may not, in fact, be available on all platforms (currently only Unix
1123 platforms with nanosleep(2) may provide it) in which case this is the same
1124 as calling wxMilliSleep() with the argument of @e microseconds/1000.
1128 void wxMicroSleep(unsigned long microseconds
);
1131 Sleeps for the specified number of milliseconds. Notice that usage of this
1132 function is encouraged instead of calling usleep(3) directly because the
1133 standard @e usleep() function is not MT safe.
1137 void wxMilliSleep(unsigned long milliseconds
);
1140 Returns a string representing the current date and time.
1147 Sleeps for the specified number of seconds.
1151 void wxSleep(int secs
);
1154 @deprecated This function is deprecated because its name is misleading:
1155 notice that the argument is in milliseconds, not microseconds.
1156 Please use either wxMilliSleep() or wxMicroSleep() depending on
1157 the resolution you need.
1159 Sleeps for the specified number of milliseconds.
1163 void wxUsleep(unsigned long milliseconds
);