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 Notice that under MSW if @a winToSkip appears in the taskbar, the user
42 will be able to close the entire application (even though its main
43 window is disabled) by right clicking on the taskbar icon and selecting
44 the appropriate "Close" command from the context menu. To prevent this
45 from happening you may want to use wxFRAME_TOOL_WINDOW, if applicable,
46 or wxFRAME_NO_TASKBAR style when creating the window that will remain
49 wxWindowDisabler(wxWindow
* winToSkip
);
52 Reenables the windows disabled by the constructor.
62 This class makes it easy to tell your user that the program is temporarily
63 busy. Just create a wxBusyCursor object on the stack, and within the
64 current scope, the hourglass will be shown.
71 for (int i = 0; i < 100000; i++)
75 It works by calling wxBeginBusyCursor() in the constructor, and
76 wxEndBusyCursor() in the destructor.
81 @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
87 Constructs a busy cursor object, calling wxBeginBusyCursor().
89 wxBusyCursor(const wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
92 Destroys the busy cursor object, calling wxEndBusyCursor().
99 // ============================================================================
100 // Global functions/macros
101 // ============================================================================
104 /** @addtogroup group_funcmacro_dialog */
108 Changes the cursor to the given cursor for all windows in the application.
109 Use wxEndBusyCursor() to revert the cursor back to its previous state.
110 These two calls can be nested, and a counter ensures that only the outer
113 @see wxIsBusy(), wxBusyCursor
117 void wxBeginBusyCursor(const wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
120 Changes the cursor back to the original cursor, for all windows in the
121 application. Use with wxBeginBusyCursor().
123 @see wxIsBusy(), wxBusyCursor
127 void wxEndBusyCursor();
130 Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
140 Ring the system bell.
142 @note This function is categorized as a GUI one and so is not thread-safe.
149 Shows a message box with the information about the wxWidgets build used,
150 including its version, most important build parameters and the version of
151 the underlying GUI toolkit. This is mainly used for diagnostic purposes
152 and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
153 doesn't otherwise handle this event.
156 @see wxGetLibraryVersionInfo()
159 void wxInfoMessageBox(wxWindow
* parent
);
163 /** @addtogroup group_funcmacro_version */
167 Get wxWidgets version information.
174 wxVersionInfo
wxGetLibraryVersionInfo();
180 /** @addtogroup group_funcmacro_env */
184 A map type containing environment variables names and values.
186 This type is used with wxGetEnvMap() function and wxExecuteEnv structure
187 optionally passed to wxExecute().
193 typedef wxStringToStringHashMap wxEnvVariableHashMap
;
196 This is a macro defined as @c getenv() or its wide char version in Unicode
199 Note that under Win32 it may not return correct value for the variables set
200 with wxSetEnv(), use wxGetEnv() function instead.
204 wxChar
* wxGetenv(const wxString
& var
);
207 Returns the current value of the environment variable @a var in @a value.
209 @a value may be @NULL if you just want to know if the variable exists and
210 are not interested in its value.
212 Returns @true if the variable exists, @false otherwise.
216 bool wxGetEnv(const wxString
& var
, wxString
* value
);
219 Sets the value of the environment variable @a var (adding it if necessary)
222 Notice that under Windows platforms the program may have two different
223 environment blocks: the first one is that of a Windows process and is
224 always present, but the CRT may maintain its own independent copy of the
225 environment. wxSetEnv() will always update the first copy, which means that
226 wxGetEnv(), which uses it directly, will always return the expected value
227 after this call. But wxSetEnv() only updates the second copy for some
228 compilers/CRT implementations (currently only MSVC and MinGW which uses the
229 same MSVC CRT) and so using wxGetenv() (notice the difference in case) may
230 not return the updated value.
233 The environment variable to be set, must not contain @c '=' character.
235 New value of the variable.
237 @true on success or @false if changing the value failed.
243 bool wxSetEnv(const wxString
& var
, const wxString
& value
);
246 Removes the variable @a var from the environment.
248 wxGetEnv() will return @NULL after the call to this function.
250 Returns @true on success.
254 bool wxUnsetEnv(const wxString
& var
);
257 Fill a map with the complete content of current environment.
259 The map will contain the environment variable names as keys and their
263 The environment map to fill, must be non-@NULL.
265 @true if environment was successfully retrieved or @false otherwise.
271 bool wxGetEnvMap(wxEnvVariableHashMap
*map
);
276 /** @addtogroup group_funcmacro_misc */
280 Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
281 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
282 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
283 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
284 feature is not implemented (currently everywhere but MS Windows).
288 wxBatteryState
wxGetBatteryState();
291 Returns the type of power source as one of @c wxPOWER_SOCKET,
292 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
293 default on platforms where this feature is not implemented (currently
294 everywhere but MS Windows).
298 wxPowerType
wxGetPowerType();
301 Under X only, returns the current display name.
303 @see wxSetDisplayName()
307 wxString
wxGetDisplayName();
310 For normal keys, returns @true if the specified key is currently down.
312 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
313 the key is toggled such that its LED indicator is lit. There is currently
314 no way to test whether togglable keys are up or down.
316 Even though there are virtual key codes defined for mouse buttons, they
317 cannot be used with this function currently.
321 bool wxGetKeyState(wxKeyCode key
);
324 Returns the mouse position in screen coordinates.
328 wxPoint
wxGetMousePosition();
331 Returns the current state of the mouse. Returns a wxMouseState instance
332 that contains the current position of the mouse pointer in screen
333 coordinates, as well as boolean values indicating the up/down status of the
334 mouse buttons and the modifier keys.
338 wxMouseState
wxGetMouseState();
341 This function enables or disables all top level windows. It is used by
346 void wxEnableTopLevelWindows(bool enable
= true);
349 Find the deepest window at the given mouse position in screen coordinates,
350 returning the window if found, or @NULL if not.
354 wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
357 @deprecated Replaced by wxWindow::FindWindowByLabel().
359 Find a window by its label. Depending on the type of window, the label may
360 be a window title or panel item label. If @a parent is @NULL, the search
361 will start from all top-level frames and dialog boxes; if non-@NULL, the
362 search will be limited to the given window hierarchy. The search is
363 recursive in both cases.
367 wxWindow
* wxFindWindowByLabel(const wxString
& label
,
368 wxWindow
* parent
= NULL
);
371 @deprecated Replaced by wxWindow::FindWindowByName().
373 Find a window by its name (as given in a window constructor or @e Create
374 function call). If @a parent is @NULL, the search will start from all
375 top-level frames and dialog boxes; if non-@NULL, the search will be limited
376 to the given window hierarchy. The search is recursive in both cases.
378 If no such named window is found, wxFindWindowByLabel() is called.
382 wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
* parent
= NULL
);
385 Find a menu item identifier associated with the given frame's menu bar.
389 int wxFindMenuItemId(wxFrame
* frame
, const wxString
& menuString
,
390 const wxString
& itemString
);
393 @deprecated Ids generated by it can conflict with the Ids defined by the
394 user code, use @c wxID_ANY to assign ids which are guaranteed
395 to not conflict with the user-defined ids for the controls and
396 menu items you create instead of using this function.
398 Generates an integer identifier unique to this run of the program.
405 Ensures that Ids subsequently generated by wxNewId() do not clash with the
410 void wxRegisterId(long id
);
413 Opens the @a document in the application associated with the files of this
416 The @a flags parameter is currently not used
418 Returns @true if the application was successfully launched.
420 @see wxLaunchDefaultBrowser(), wxExecute()
424 bool wxLaunchDefaultApplication(const wxString
& document
, int flags
= 0);
427 Opens the @a url in user's default browser.
429 If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
430 window is opened for the URL (currently this is only supported under
433 And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
434 a busy cursor is shown while the browser is being launched (using
437 The parameter @a url is interpreted as follows:
438 - if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "mailto:")
439 it is passed to the appropriate browser configured in the user system.
440 - if it has no valid scheme (e.g. it's a local file path without the @c "file:"
441 prefix), then ::wxFileExists and ::wxDirExists are used to test if it's a
442 local file/directory; if it is, then the browser is called with the
443 @a url parameter eventually prefixed by @c "file:".
444 - if it has no valid scheme and it's not a local file/directory, then @c "http:"
445 is prepended and the browser is called.
447 Returns @true if the application was successfully launched.
449 @note For some configurations of the running user, the application which is
450 launched to open the given URL may be URL-dependent (e.g. a browser
451 may be used for local URLs while another one may be used for remote
454 @see wxLaunchDefaultApplication(), wxExecute()
458 bool wxLaunchDefaultBrowser(const wxString
& url
, int flags
= 0);
461 Loads a user-defined Windows resource as a string. If the resource is
462 found, the function creates a new character array and copies the data into
463 it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
465 The resource must be defined in the @c .rc file using the following syntax:
468 myResource TEXT file.ext
471 Where @c file.ext is a file that the resource compiler can find.
473 This function is available under Windows only.
477 wxString
wxLoadUserResource(const wxString
& resourceName
,
478 const wxString
& resourceType
= "TEXT");
481 @deprecated Replaced by wxWindow::Close(). See the
482 @ref overview_windowdeletion "window deletion overview".
484 Tells the system to delete the specified object when all other events have
485 been processed. In some environments, it is necessary to use this instead
486 of deleting a frame directly with the delete operator, because some GUIs
487 will still send events to a deleted window.
491 void wxPostDelete(wxObject
* object
);
495 Compare function type for use with wxQsort()
499 typedef int (*wxSortCallback
)(const void* pItem1
, const void* pItem2
, const void* user_data
);
502 Function implementing quick sort algorithm.
504 This function sorts @a total_elems objects of size @a size located at @a
505 pbase. It uses @a cmp function for comparing them and passes @a user_data
506 pointer to the comparison function each time it's called.
510 void wxQsort(void* pbase
, size_t total_elems
,
511 size_t size
, wxSortCallback cmp
, const void* user_data
);
515 Under X only, sets the current display name. This is the X host and display
516 name such as "colonsay:0.0", and the function indicates which display
517 should be used for creating windows from this point on. Setting the display
518 within an application allows multiple displays to be used.
520 @see wxGetDisplayName()
524 void wxSetDisplayName(const wxString
& displayName
);
527 Strips any menu codes from @a str and returns the result.
529 By default, the functions strips both the mnemonics character (@c '&')
530 which is used to indicate a keyboard shortkey, and the accelerators, which
531 are used only in the menu items and are separated from the main text by the
532 @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
533 @c wxStrip_Accel to strip only the former or the latter part, respectively.
535 Notice that in most cases wxMenuItem::GetLabelFromText() or
536 wxControl::GetLabelText() can be used instead.
540 wxString
wxStripMenuCodes(const wxString
& str
, int flags
= wxStrip_All
);
546 /** @addtogroup group_funcmacro_networkuseros */
550 Copies the user's email address into the supplied buffer, by concatenating
551 the values returned by wxGetFullHostName() and wxGetUserId().
553 @return @true if successful, @false otherwise.
557 wxString
wxGetEmailAddress();
560 @deprecated Use wxGetEmailAddress() instead.
562 @param buf Buffer to store the email address in.
563 @param sz Size of the buffer.
565 @return @true if successful, @false otherwise.
569 bool wxGetEmailAddress(char* buf
, int sz
);
572 Returns the amount of free memory in bytes under environments which support
573 it, and -1 if not supported or failed to perform measurement.
577 wxMemorySize
wxGetFreeMemory();
580 Return the (current) user's home directory.
582 @see wxGetUserHome(), wxStandardPaths
586 wxString
wxGetHomeDir();
589 Copies the current host machine's name into the supplied buffer. Please
590 note that the returned name is @e not fully qualified, i.e. it does not
591 include the domain name.
593 Under Windows or NT, this function first looks in the environment variable
594 SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
595 section of the WIN.INI file is tried.
597 @return The hostname if successful or an empty string otherwise.
599 @see wxGetFullHostName()
603 wxString
wxGetHostName();
606 @deprecated Use wxGetHostName() instead.
608 @param buf Buffer to store the host name in.
609 @param sz Size of the buffer.
611 @return @true if successful, @false otherwise.
615 bool wxGetHostName(char* buf
, int sz
);
618 Returns the FQDN (fully qualified domain host name) or an empty string on
625 wxString
wxGetFullHostName();
628 Returns the home directory for the given user. If the @a user is empty
629 (default value), this function behaves like wxGetHomeDir() (i.e. returns
630 the current user home directory).
632 If the home directory couldn't be determined, an empty string is returned.
636 wxString
wxGetUserHome(const wxString
& user
= wxEmptyString
);
639 This function returns the "user id" also known as "login name" under Unix
640 (i.e. something like "jsmith"). It uniquely identifies the current user (on
641 this system). Under Windows or NT, this function first looks in the
642 environment variables USER and LOGNAME; if neither of these is found, the
643 entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
645 @return The login name if successful or an empty string otherwise.
651 wxString
wxGetUserId();
654 @deprecated Use wxGetUserId() instead.
656 @param buf Buffer to store the login name in.
657 @param sz Size of the buffer.
659 @return @true if successful, @false otherwise.
663 bool wxGetUserId(char* buf
, int sz
);
666 This function returns the full user name (something like "Mr. John Smith").
668 Under Windows or NT, this function looks for the entry UserName in the
669 wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
670 Current in the section User of the PENWIN.INI file is used.
672 @return The full user name if successful or an empty string otherwise.
678 wxString
wxGetUserName();
681 @deprecated Use wxGetUserName() instead.
683 @param buf Buffer to store the full user name in.
684 @param sz Size of the buffer.
686 @return @true if successful, @false otherwise.
690 bool wxGetUserName(char* buf
, int sz
);
693 Returns the string containing the description of the current platform in a
694 user-readable form. For example, this function may return strings like
695 "Windows NT Version 4.0" or "Linux 2.2.2 i386".
697 @see wxGetOsVersion()
701 wxString
wxGetOsDescription();
704 Gets the version and the operating system ID for currently running OS.
705 The returned wxOperatingSystemId value can be used for a basic categorization
706 of the OS family; the major and minor version numbers allows to detect a specific
709 For Unix-like systems (@c wxOS_UNIX) the major and minor version integers will
710 contain the kernel major and minor version numbers (as returned by the
711 'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.
713 For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the
714 natural version numbers associated with the OS; e.g. "10" and "6" if the machine
715 is using Mac OS X Snow Leopard.
717 For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will
718 contain the following values:
720 @row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>}
721 @row3col{Windows 7, 6, 1}
722 @row3col{Windows Server 2008 R2, 6, 1}
723 @row3col{Windows Server 2008, 6, 0}
724 @row3col{Windows Vista, 6, 0}
725 @row3col{Windows Server 2003 R2, 5, 2}
726 @row3col{Windows Server 2003, 5, 2}
727 @row3col{Windows XP, 5, 1}
728 @row3col{Windows 2000, 5, 0}
730 See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a>
731 for more info about the values above.
733 @see wxGetOsDescription(), wxPlatformInfo
737 wxOperatingSystemId
wxGetOsVersion(int* major
= NULL
, int* minor
= NULL
);
740 Returns @true if the operating system the program is running under is 64
741 bit. The check is performed at run-time and may differ from the value
742 available at compile-time (at compile-time you can just check if
743 <tt>sizeof(void*) == 8</tt>) since the program could be running in
744 emulation mode or in a mixed 32/64 bit system (bi-architecture operating
747 @note This function is not 100% reliable on some systems given the fact
748 that there isn't always a standard way to do a reliable check on the
753 bool wxIsPlatform64Bit();
756 Returns @true if the current platform is little endian (instead of big
757 endian). The check is performed at run-time.
759 @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"
763 bool wxIsPlatformLittleEndian();
766 Returns a structure containing informations about the currently running
769 This function uses the @c lsb_release utility which is part of the
770 <tt>Linux Standard Base Core</tt> specification
771 (see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB
772 release 1.0 (released in 2001).
773 The @c lsb_release utility is very common on modern Linux distributions but in
774 case it's not available, then this function will return a ::wxLinuxDistributionInfo
775 structure containing empty strings.
777 This function is Linux-specific and is only available when the @c __LINUX__
780 wxLinuxDistributionInfo
wxGetLinuxDistributionInfo();
786 /** @addtogroup group_funcmacro_procctrl */
792 This structure can optionally be passed to wxExecute() to specify
793 additional options to use for the child process.
802 The initial working directory for the new process.
804 If this field is empty, the current working directory of this process
810 The environment variable map.
812 If the map is empty, the environment variables of the current process
813 are also used for the child one, otherwise only the variables defined
814 in this map are used.
816 wxEnvVariableHashMap env
;
820 Bit flags that can be used with wxExecute().
825 Execute the process asynchronously.
827 Notice that, due to its value, this is the default.
832 Execute the process synchronously.
837 Always show the child process console under MSW.
839 The child console is hidden by default if the child IO is redirected,
840 this flag allows to change this and show it nevertheless.
842 This flag is ignored under the other platforms.
844 wxEXEC_SHOW_CONSOLE
= 2,
847 Make the new process a group leader.
849 Under Unix, if the process is the group leader then passing
850 wxKILL_CHILDREN to wxKill() kills all children as well as pid.
852 Under MSW, applies only to console applications and is only supported
853 under NT family (i.e. not under Windows 9x). It corresponds to the
854 native @c CREATE_NEW_PROCESS_GROUP and, in particular, ensures that
855 Ctrl-Break signals will be sent to all children of this process as well
856 to the process itself. Support for this flag under MSW was added in
857 version 2.9.4 of wxWidgets.
859 wxEXEC_MAKE_GROUP_LEADER
= 4,
862 Don't disable the program UI while running the child synchronously.
864 By default synchronous execution disables all program windows to avoid
865 that the user interacts with the program while the child process is
866 running, you can use this flag to prevent this from happening.
868 This flag can only be used with ::wxEXEC_SYNC.
870 wxEXEC_NODISABLE
= 8,
873 Don't dispatch events while the child process is executed.
875 By default, the event loop is run while waiting for synchronous
876 execution to complete and this flag can be used to simply block the
877 main process until the child process finishes
879 This flag can only be used with ::wxEXEC_SYNC.
881 wxEXEC_NOEVENTS
= 16,
884 Hide child process console under MSW.
886 Under MSW, hide the console of the child process if it has one,
887 even if its IO is not redirected.
889 This flag is ignored under the other platforms.
891 wxEXEC_HIDE_CONSOLE
= 32,
894 Convenient synonym for flags given system()-like behaviour.
896 wxEXEC_BLOCK
= wxEXEC_SYNC
| wxEXEC_NOEVENTS
899 Executes another program in Unix or Windows.
901 In the overloaded versions of this function, if @a flags parameter contains
902 @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
903 it contains @c wxEXEC_SYNC, the current application waits until the other
904 program has terminated.
906 In the case of synchronous execution, the return value is the exit code of
907 the process (which terminates by the moment the function returns) and will
908 be -1 if the process couldn't be started and typically 0 if the process
909 terminated successfully. Also, while waiting for the process to terminate,
910 wxExecute() will call wxYield(). Because of this, by default this function
911 disables all application windows to avoid unexpected reentrancies which
912 could result from the users interaction with the program while the child
913 process is running. If you are sure that it is safe to not disable the
914 program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
915 automatic disabling from happening.
917 For asynchronous execution, however, the return value is the process id and
918 zero value indicates that the command could not be executed. As an added
919 complication, the return value of -1 in this case indicates that we didn't
920 launch a new process, but connected to the running one (this can only
921 happen when using DDE under Windows for command execution). In particular,
922 in this case only, the calling code will not get the notification about
925 If @a callback isn't @NULL and if execution is asynchronous,
926 wxProcess::OnTerminate() will be called when the process finishes.
927 Specifying this parameter also allows you to redirect the standard input
928 and/or output of the process being launched by calling
929 wxProcess::Redirect().
931 Under Windows, when launching a console process its console is shown by
932 default but hidden if its IO is redirected. Both of these default
933 behaviours may be overridden: if ::wxEXEC_HIDE_CONSOLE is specified, the
934 console will never be shown. If ::wxEXEC_SHOW_CONSOLE is used, the console
935 will be shown even if the child process IO is redirected. Neither of these
936 flags affect non-console Windows applications or does anything under the
939 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
940 the new process is a group leader (this will create a new session if
941 needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
942 well as all of its children (except those which have started their own
943 session). Under MSW, this flag can be used with console processes only and
944 corresponds to the native @c CREATE_NEW_PROCESS_GROUP flag.
946 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
947 place while the child process is running. It should be only used for very
948 short-lived processes as otherwise the application windows risk becoming
949 unresponsive from the users point of view. As this flag only makes sense
950 with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
951 flags is provided as a convenience.
953 @note Currently wxExecute() can only be used from the main thread, calling
954 this function from another thread will result in an assert failure in
955 debug build and won't work.
958 The command to execute and any parameters to pass to it as a single
959 string, i.e. "emacs file.txt".
961 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
962 wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, wxEXEC_MAKE_GROUP_LEADER (in
963 either case) or wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK,
964 which is equal to their combination, in wxEXEC_SYNC case.
966 An optional pointer to wxProcess.
968 An optional pointer to additional parameters for the child process,
969 such as its initial working directory and environment variables. This
970 parameter is available in wxWidgets 2.9.2 and later only.
972 @see wxShell(), wxProcess, @ref page_samples_exec,
973 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
978 In wxPerl this function is called @c Wx::ExecuteCommand.
981 long wxExecute(const wxString
& command
, int flags
= wxEXEC_ASYNC
,
982 wxProcess
* callback
= NULL
,
983 const wxExecuteEnv
* env
= NULL
);
986 /** @addtogroup group_funcmacro_procctrl */
989 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
990 please see its documentation for general information.
992 This version takes an array of values: a command, any number of arguments,
996 The command to execute should be the first element of this array, any
997 additional ones are the command parameters and the array must be
998 terminated with a @NULL pointer.
1000 Same as for wxExecute(const wxString&,int,wxProcess*) overload.
1002 An optional pointer to wxProcess.
1004 An optional pointer to additional parameters for the child process,
1005 such as its initial working directory and environment variables. This
1006 parameter is available in wxWidgets 2.9.2 and later only.
1008 @see wxShell(), wxProcess, @ref page_samples_exec,
1009 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
1014 In wxPerl this function is called @c Wx::ExecuteArgs.
1017 long wxExecute(char** argv
, int flags
= wxEXEC_ASYNC
,
1018 wxProcess
* callback
= NULL
,
1019 const wxExecuteEnv
*env
= NULL
);
1020 long wxExecute(wchar_t** argv
, int flags
= wxEXEC_ASYNC
,
1021 wxProcess
* callback
= NULL
,
1022 const wxExecuteEnv
*env
= NULL
);
1025 /** @addtogroup group_funcmacro_procctrl */
1029 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
1030 please see its documentation for general information.
1032 This version can be used to execute a process (always synchronously, the
1033 contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
1034 the array @e output.
1037 The command to execute and any parameters to pass to it as a single
1040 The string array where the stdout of the executed process is saved.
1042 Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
1044 An optional pointer to additional parameters for the child process,
1045 such as its initial working directory and environment variables. This
1046 parameter is available in wxWidgets 2.9.2 and later only.
1048 @see wxShell(), wxProcess, @ref page_samples_exec,
1049 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
1054 This function is called @c Wx::ExecuteStdout: it only takes the
1055 @a command argument, and returns a 2-element list (@c status, @c output),
1056 where @c output in an array reference.
1059 long wxExecute(const wxString
& command
, wxArrayString
& output
, int flags
= 0,
1060 const wxExecuteEnv
*env
= NULL
);
1063 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
1064 please see its documentation for general information.
1066 This version adds the possibility to additionally capture the messages from
1067 standard error output in the @a errors array. As with the above overload
1068 capturing standard output only, execution is always synchronous.
1071 The command to execute and any parameters to pass to it as a single
1074 The string array where the stdout of the executed process is saved.
1076 The string array where the stderr of the executed process is saved.
1078 Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
1080 An optional pointer to additional parameters for the child process,
1081 such as its initial working directory and environment variables. This
1082 parameter is available in wxWidgets 2.9.2 and later only.
1084 @see wxShell(), wxProcess, @ref page_samples_exec,
1085 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
1090 This function is called @c Wx::ExecuteStdoutStderr: it only takes the
1091 @a command argument, and returns a 3-element list (@c status, @c output,
1092 @c errors), where @c output and @c errors are array references.
1095 long wxExecute(const wxString
& command
, wxArrayString
& output
,
1096 wxArrayString
& errors
, int flags
= 0,
1097 const wxExecuteEnv
*env
= NULL
);
1100 Returns the number uniquely identifying the current process in the system.
1101 If an error occurs, 0 is returned.
1105 unsigned long wxGetProcessId();
1108 Equivalent to the Unix kill function: send the given signal @a sig to the
1109 process with PID @a pid.
1111 The valid signal values are:
1116 wxSIGNONE = 0, // verify if the process exists under Unix
1125 wxSIGKILL, // forcefully kill, dangerous!
1131 wxSIGTERM // terminate the process gently
1135 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
1136 both Unix and Windows but all the other signals are equivalent to
1137 @c wxSIGTERM under Windows.
1139 Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
1140 it will be filled with a value from the @c wxKillError enum:
1145 wxKILL_OK, // no error
1146 wxKILL_BAD_SIGNAL, // no such signal
1147 wxKILL_ACCESS_DENIED, // permission denied
1148 wxKILL_NO_PROCESS, // no such process
1149 wxKILL_ERROR // another, unspecified error
1153 The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
1154 wxKILL_CHILDREN, in which case the child processes of this process will be
1155 killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
1156 have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
1159 @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec
1163 int wxKill(long pid
, wxSignal sig
= wxSIGTERM
,
1164 wxKillError
* rc
= NULL
, int flags
= wxKILL_NOCHILDREN
);
1167 Executes a command in an interactive shell window. If no command is
1168 specified, then just the shell is spawned.
1170 @see wxExecute(), @ref page_samples_exec
1174 bool wxShell(const wxString
& command
= wxEmptyString
);
1177 This function shuts down or reboots the computer depending on the value of
1180 @note Note that performing the shutdown requires the corresponding access
1181 rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT)
1182 and that this function is only implemented under Unix and MSW.
1185 One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
1186 @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
1187 combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by
1188 forcefully terminating all the applications. As doing this can result
1189 in a data loss, this flag shouldn't be used unless really necessary.
1191 @return @true on success, @false if an error occurred.
1195 bool wxShutdown(int flags
= wxSHUTDOWN_POWEROFF
);
1201 /** @addtogroup group_funcmacro_time */
1205 Sleeps for the specified number of microseconds. The microsecond resolution
1206 may not, in fact, be available on all platforms (currently only Unix
1207 platforms with nanosleep(2) may provide it) in which case this is the same
1208 as calling wxMilliSleep() with the argument of @e microseconds/1000.
1212 void wxMicroSleep(unsigned long microseconds
);
1215 Sleeps for the specified number of milliseconds. Notice that usage of this
1216 function is encouraged instead of calling usleep(3) directly because the
1217 standard @e usleep() function is not MT safe.
1221 void wxMilliSleep(unsigned long milliseconds
);
1224 Returns a string representing the current date and time.
1231 Sleeps for the specified number of seconds.
1235 void wxSleep(int secs
);
1238 @deprecated This function is deprecated because its name is misleading:
1239 notice that the argument is in milliseconds, not microseconds.
1240 Please use either wxMilliSleep() or wxMicroSleep() depending on
1241 the resolution you need.
1243 Sleeps for the specified number of milliseconds.
1247 void wxUsleep(unsigned long milliseconds
);