]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/utils.h
Compilation for wchar mode
[wxWidgets.git] / interface / wx / utils.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: utils.h
3 // Purpose: interface of various utility classes and functions
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxWindowDisabler
11
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
14 destructor.
15
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.
18
19 @library{wxcore}
20 @category{misc}
21
22 @see wxBusyCursor
23 */
24 class wxWindowDisabler
25 {
26 public:
27 /**
28 Disables all top level windows of the applications.
29
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.
32
33 @since 2.9.0
34 */
35 wxWindowDisabler(bool disable = true);
36
37 /**
38 Disables all top level windows of the applications with the exception
39 of @a winToSkip if it is not @NULL.
40 */
41 wxWindowDisabler(wxWindow* winToSkip);
42
43 /**
44 Reenables the windows disabled by the constructor.
45 */
46 ~wxWindowDisabler();
47 };
48
49
50
51 /**
52 @class wxBusyCursor
53
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.
57
58 For example:
59
60 @code
61 wxBusyCursor wait;
62
63 for (int i = 0; i < 100000; i++)
64 DoACalculation();
65 @endcode
66
67 It works by calling wxBeginBusyCursor() in the constructor, and
68 wxEndBusyCursor() in the destructor.
69
70 @library{wxcore}
71 @category{misc}
72
73 @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
74 */
75 class wxBusyCursor
76 {
77 public:
78 /**
79 Constructs a busy cursor object, calling wxBeginBusyCursor().
80 */
81 wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
82
83 /**
84 Destroys the busy cursor object, calling wxEndBusyCursor().
85 */
86 ~wxBusyCursor();
87 };
88
89
90
91 /**
92 @class wxMouseState
93
94 Represents the mouse state.
95
96 The methods of this class generally mirror the corresponding methods of
97 wxMouseEvent.
98
99 This class is implemented entirely in @<wx/utils.h@>, meaning no extra
100 library needs to be linked to use this class.
101
102 @category{misc}
103
104 @see wxGetMouseState()
105 */
106 class wxMouseState
107 {
108 public:
109 /**
110 Default constructor.
111 */
112 wxMouseState();
113
114 /**
115 Returns X coordinate of the physical mouse event position.
116 */
117 wxCoord GetX() const;
118 /**
119 Returns Y coordinate of the physical mouse event position.
120 */
121 wxCoord GetY() const;
122 /**
123 Returns the physical mouse position.
124 */
125 wxPoint GetPosition() const;
126
127 /**
128 Returns @true if the left mouse button changed to down.
129 */
130 bool LeftDown() const;
131 /**
132 Returns @true if the middle mouse button changed to down.
133 */
134 bool MiddleDown() const;
135 /**
136 Returns @true if the right mouse button changed to down.
137 */
138 bool RightDown() const;
139 /**
140 Returns @true if the first extra button mouse button changed to down.
141 */
142 bool Aux1Down() const;
143 /**
144 Returns @true if the second extra button mouse button changed to down.
145 */
146 bool Aux2Down() const;
147
148 /**
149 Returns @true if the control key is down.
150 */
151 bool ControlDown() const;
152 /**
153 Returns @true if the shift key is down.
154 */
155 bool ShiftDown() const;
156 /**
157 Returns @true if the alt key is down.
158 */
159 bool AltDown() const;
160 /**
161 Returns @true if the meta key is down.
162 */
163 bool MetaDown() const;
164 /**
165 Same as MetaDown() under Mac systems, ControlDown() for the others.
166 */
167 bool CmdDown() const;
168 };
169
170
171 // ============================================================================
172 // Global functions/macros
173 // ============================================================================
174
175
176 /** @ingroup group_funcmacro_dialog */
177 //@{
178
179 /**
180 Changes the cursor to the given cursor for all windows in the application.
181 Use wxEndBusyCursor() to revert the cursor back to its previous state.
182 These two calls can be nested, and a counter ensures that only the outer
183 calls take effect.
184
185 @see wxIsBusy(), wxBusyCursor
186
187 @header{wx/utils.h}
188 */
189 void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
190
191 /**
192 Changes the cursor back to the original cursor, for all windows in the
193 application. Use with wxBeginBusyCursor().
194
195 @see wxIsBusy(), wxBusyCursor
196
197 @header{wx/utils.h}
198 */
199 void wxEndBusyCursor();
200
201 /**
202 Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
203 calls.
204
205 @see wxBusyCursor.
206
207 @header{wx/utils.h}
208 */
209 bool wxIsBusy();
210
211 /**
212 Ring the system bell.
213
214 @note This function is categorized as a GUI one and so is not thread-safe.
215
216 @header{wx/utils.h}
217 */
218 void wxBell();
219
220 /**
221 Shows a message box with the information about the wxWidgets build used,
222 including its version, most important build parameters and the version of
223 the underlying GUI toolkit. This is mainly used for diagnostic purposes
224 and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
225 doesn't otherwise handle this event.
226
227 @since 2.9.0
228
229 @header{wx/utils.h}
230 */
231 void wxInfoMessageBox(wxWindow parent = NULL);
232
233 //@}
234
235
236
237 /** @ingroup group_funcmacro_env */
238 //@{
239
240 /**
241 This is a macro defined as @c getenv() or its wide char version in Unicode
242 mode.
243
244 Note that under Win32 it may not return correct value for the variables set
245 with wxSetEnv(), use wxGetEnv() function instead.
246
247 @header{wx/utils.h}
248 */
249 wxChar* wxGetenv(const wxString& var);
250
251 /**
252 Returns the current value of the environment variable @c var in @c value.
253 @c value may be @NULL if you just want to know if the variable exists and
254 are not interested in its value.
255
256 Returns @true if the variable exists, @false otherwise.
257
258 @header{wx/utils.h}
259 */
260 bool wxGetEnv(const wxString& var, wxString* value);
261
262 /**
263 Sets the value of the environment variable @c var (adding it if necessary)
264 to @c value.
265
266 Returns @true on success.
267
268 @see wxUnsetEnv()
269
270 @header{wx/utils.h}
271 */
272 bool wxSetEnv(const wxString& var, const wxString& value);
273
274 /**
275 Removes the variable @c var from the environment. wxGetEnv() will return
276 @NULL after the call to this function.
277
278 Returns @true on success.
279
280 @header{wx/utils.h}
281 */
282 bool wxUnsetEnv(const wxString& var);
283
284 //@}
285
286
287
288 /** @ingroup group_funcmacro_misc */
289 //@{
290
291 /**
292 Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
293 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
294 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
295 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
296 feature is not implemented (currently everywhere but MS Windows).
297
298 @header{wx/utils.h}
299 */
300 wxBatteryState wxGetBatteryState();
301
302 /**
303 Returns the type of power source as one of @c wxPOWER_SOCKET,
304 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
305 default on platforms where this feature is not implemented (currently
306 everywhere but MS Windows).
307
308 @header{wx/utils.h}
309 */
310 wxPowerType wxGetPowerType();
311
312 /**
313 Under X only, returns the current display name.
314
315 @see wxSetDisplayName()
316
317 @header{wx/utils.h}
318 */
319 wxString wxGetDisplayName();
320
321 /**
322 For normal keys, returns @true if the specified key is currently down.
323
324 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
325 the key is toggled such that its LED indicator is lit. There is currently
326 no way to test whether togglable keys are up or down.
327
328 Even though there are virtual key codes defined for mouse buttons, they
329 cannot be used with this function currently.
330
331 @header{wx/utils.h}
332 */
333 bool wxGetKeyState(wxKeyCode key);
334
335 /**
336 Returns the mouse position in screen coordinates.
337
338 @header{wx/utils.h}
339 */
340 wxPoint wxGetMousePosition();
341
342 /**
343 Returns the current state of the mouse. Returns a wxMouseState instance
344 that contains the current position of the mouse pointer in screen
345 coordinates, as well as boolean values indicating the up/down status of the
346 mouse buttons and the modifier keys.
347
348 @header{wx/utils.h}
349 */
350 wxMouseState wxGetMouseState();
351
352 /**
353 This function enables or disables all top level windows. It is used by
354 wxSafeYield().
355
356 @header{wx/utils.h}
357 */
358 void wxEnableTopLevelWindows(bool enable = true);
359
360 /**
361 Find the deepest window at the given mouse position in screen coordinates,
362 returning the window if found, or @NULL if not.
363
364 @header{wx/utils.h}
365 */
366 wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
367
368 /**
369 @deprecated Replaced by wxWindow::FindWindowByLabel().
370
371 Find a window by its label. Depending on the type of window, the label may
372 be a window title or panel item label. If @a parent is @NULL, the search
373 will start from all top-level frames and dialog boxes; if non-@NULL, the
374 search will be limited to the given window hierarchy. The search is
375 recursive in both cases.
376
377 @header{wx/utils.h}
378 */
379 wxWindow* wxFindWindowByLabel(const wxString& label,
380 wxWindow* parent = NULL);
381
382 /**
383 @deprecated Replaced by wxWindow::FindWindowByName().
384
385 Find a window by its name (as given in a window constructor or @e Create
386 function call). If @a parent is @NULL, the search will start from all
387 top-level frames and dialog boxes; if non-@NULL, the search will be limited
388 to the given window hierarchy. The search is recursive in both cases.
389
390 If no such named window is found, wxFindWindowByLabel() is called.
391
392 @header{wx/utils.h}
393 */
394 wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
395
396 /**
397 Find a menu item identifier associated with the given frame's menu bar.
398
399 @header{wx/utils.h}
400 */
401 int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
402 const wxString& itemString);
403
404 /**
405 @deprecated Ids generated by it can conflict with the Ids defined by the
406 user code, use @c wxID_ANY to assign ids which are guaranteed
407 to not conflict with the user-defined ids for the controls and
408 menu items you create instead of using this function.
409
410 Generates an integer identifier unique to this run of the program.
411
412 @header{wx/utils.h}
413 */
414 long wxNewId();
415
416 /**
417 Ensures that Ids subsequently generated by wxNewId() do not clash with the
418 given @a id.
419
420 @header{wx/utils.h}
421 */
422 void wxRegisterId(long id);
423
424 /**
425 Opens the @a url in user's default browser.
426
427 If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
428 window is opened for the URL (currently this is only supported under
429 Windows).
430
431 And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
432 a busy cursor is shown while the browser is being launched (using
433 wxBusyCursor).
434
435 The @a url may also be a local file path (with or without the "file://"
436 prefix), if it doesn't correspond to an existing file and the URL has no
437 scheme "http://" is prepended to it by default.
438
439 Returns @true if the application was successfully launched.
440
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
444 URLs).
445
446 @header{wx/utils.h}
447 */
448 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
449
450 /**
451 Loads a user-defined Windows resource as a string. If the resource is
452 found, the function creates a new character array and copies the data into
453 it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
454
455 The resource must be defined in the @c .rc file using the following syntax:
456
457 @code
458 myResource TEXT file.ext
459 @endcode
460
461 Where @c file.ext is a file that the resource compiler can find.
462
463 This function is available under Windows only.
464
465 @header{wx/utils.h}
466 */
467 wxString wxLoadUserResource(const wxString& resourceName,
468 const wxString& resourceType = "TEXT");
469
470 /**
471 @deprecated Replaced by wxWindow::Close(). See the
472 @ref overview_windowdeletion "window deletion overview".
473
474 Tells the system to delete the specified object when all other events have
475 been processed. In some environments, it is necessary to use this instead
476 of deleting a frame directly with the delete operator, because some GUIs
477 will still send events to a deleted window.
478
479 @header{wx/utils.h}
480 */
481 void wxPostDelete(wxObject* object);
482
483 /**
484 Under X only, sets the current display name. This is the X host and display
485 name such as "colonsay:0.0", and the function indicates which display
486 should be used for creating windows from this point on. Setting the display
487 within an application allows multiple displays to be used.
488
489 @see wxGetDisplayName()
490
491 @header{wx/utils.h}
492 */
493 void wxSetDisplayName(const wxString& displayName);
494
495 /**
496 Strips any menu codes from @a str and returns the result.
497
498 By default, the functions strips both the mnemonics character (@c '&')
499 which is used to indicate a keyboard shortkey, and the accelerators, which
500 are used only in the menu items and are separated from the main text by the
501 @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
502 @c wxStrip_Accel to strip only the former or the latter part, respectively.
503
504 Notice that in most cases wxMenuItem::GetLabelFromText() or
505 wxControl::GetLabelText() can be used instead.
506
507 @header{wx/utils.h}
508 */
509 wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
510
511 //@}
512
513
514
515 /** @ingroup group_funcmacro_networkuseros */
516 //@{
517
518 /**
519 Copies the user's email address into the supplied buffer, by concatenating
520 the values returned by wxGetFullHostName() and wxGetUserId().
521
522 @return @true if successful, @false otherwise.
523
524 @header{wx/utils.h}
525 */
526 wxString wxGetEmailAddress();
527
528 /**
529 @deprecated Use wxGetEmailAddress() instead.
530
531 @param buf Buffer to store the email address in.
532 @param sz Size of the buffer.
533
534 @return @true if successful, @false otherwise.
535
536 @header{wx/utils.h}
537 */
538 bool wxGetEmailAddress(char* buf, int sz);
539
540 /**
541 Returns the amount of free memory in bytes under environments which support
542 it, and -1 if not supported or failed to perform measurement.
543
544 @header{wx/utils.h}
545 */
546 wxMemorySize wxGetFreeMemory();
547
548 /**
549 Return the (current) user's home directory.
550
551 @see wxGetUserHome(), wxStandardPaths
552
553 @header{wx/utils.h}
554 */
555 wxString wxGetHomeDir();
556
557 /**
558 Copies the current host machine's name into the supplied buffer. Please
559 note that the returned name is @e not fully qualified, i.e. it does not
560 include the domain name.
561
562 Under Windows or NT, this function first looks in the environment variable
563 SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
564 section of the WIN.INI file is tried.
565
566 @return The hostname if successful or an empty string otherwise.
567
568 @see wxGetFullHostName()
569
570 @header{wx/utils.h}
571 */
572 wxString wxGetHostName();
573
574 /**
575 @deprecated Use wxGetHostName() instead.
576
577 @param buf Buffer to store the host name in.
578 @param sz Size of the buffer.
579
580 @return @true if successful, @false otherwise.
581
582 @header{wx/utils.h}
583 */
584 bool wxGetHostName(char* buf, int sz);
585
586 /**
587 Returns the FQDN (fully qualified domain host name) or an empty string on
588 error.
589
590 @see wxGetHostName()
591
592 @header{wx/utils.h}
593 */
594 wxString wxGetFullHostName();
595
596 /**
597 Returns the home directory for the given user. If the @a user is empty
598 (default value), this function behaves like wxGetHomeDir() (i.e. returns
599 the current user home directory).
600
601 If the home directory couldn't be determined, an empty string is returned.
602
603 @header{wx/utils.h}
604 */
605 wxString wxGetUserHome(const wxString& user = "");
606
607 /**
608 This function returns the "user id" also known as "login name" under Unix
609 (i.e. something like "jsmith"). It uniquely identifies the current user (on
610 this system). Under Windows or NT, this function first looks in the
611 environment variables USER and LOGNAME; if neither of these is found, the
612 entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
613
614 @return The login name if successful or an empty string otherwise.
615
616 @see wxGetUserName()
617
618 @header{wx/utils.h}
619 */
620 wxString wxGetUserId();
621
622 /**
623 @deprecated Use wxGetUserId() instead.
624
625 @param buf Buffer to store the login name in.
626 @param sz Size of the buffer.
627
628 @return @true if successful, @false otherwise.
629
630 @header{wx/utils.h}
631 */
632 bool wxGetUserId(char* buf, int sz);
633
634 /**
635 This function returns the full user name (something like "Mr. John Smith").
636
637 Under Windows or NT, this function looks for the entry UserName in the
638 wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
639 Current in the section User of the PENWIN.INI file is used.
640
641 @return The full user name if successful or an empty string otherwise.
642
643 @see wxGetUserId()
644
645 @header{wx/utils.h}
646 */
647 wxString wxGetUserName();
648
649 /**
650 @deprecated Use wxGetUserName() instead.
651
652 @param buf Buffer to store the full user name in.
653 @param sz Size of the buffer.
654
655 @return @true if successful, @false otherwise.
656
657 @header{wx/utils.h}
658 */
659 bool wxGetUserName(char* buf, int sz);
660
661 /**
662 Returns the string containing the description of the current platform in a
663 user-readable form. For example, this function may return strings like
664 "Windows NT Version 4.0" or "Linux 2.2.2 i386".
665
666 @see wxGetOsVersion()
667
668 @header{wx/utils.h}
669 */
670 wxString wxGetOsDescription();
671
672 /**
673 Gets the version and the operating system ID for currently running OS. See
674 wxPlatformInfo for more details about wxOperatingSystemId.
675
676 @see wxGetOsDescription(), wxPlatformInfo
677
678 @header{wx/utils.h}
679 */
680 wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);
681
682 /**
683 Returns @true if the operating system the program is running under is 64
684 bit. The check is performed at run-time and may differ from the value
685 available at compile-time (at compile-time you can just check if
686 <tt>sizeof(void*) == 8</tt>) since the program could be running in
687 emulation mode or in a mixed 32/64 bit system (bi-architecture operating
688 system).
689
690 @note This function is not 100% reliable on some systems given the fact
691 that there isn't always a standard way to do a reliable check on the
692 OS architecture.
693
694 @header{wx/utils.h}
695 */
696 bool wxIsPlatform64Bit();
697
698 /**
699 Returns @true if the current platform is little endian (instead of big
700 endian). The check is performed at run-time.
701
702 @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"
703
704 @header{wx/utils.h}
705 */
706 bool wxIsPlatformLittleEndian();
707
708 //@}
709
710
711
712 /** @ingroup group_funcmacro_procctrl */
713 //@{
714
715 /**
716 Executes another program in Unix or Windows.
717
718 In the overloaded versions of this function, if @a flags parameter contains
719 @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
720 it contains @c wxEXEC_SYNC, the current application waits until the other
721 program has terminated.
722
723 In the case of synchronous execution, the return value is the exit code of
724 the process (which terminates by the moment the function returns) and will
725 be -1 if the process couldn't be started and typically 0 if the process
726 terminated successfully. Also, while waiting for the process to terminate,
727 wxExecute() will call wxYield(). Because of this, by default this function
728 disables all application windows to avoid unexpected reentrancies which
729 could result from the users interaction with the program while the child
730 process is running. If you are sure that it is safe to not disable the
731 program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
732 automatic disabling from happening.
733
734 For asynchronous execution, however, the return value is the process id and
735 zero value indicates that the command could not be executed. As an added
736 complication, the return value of -1 in this case indicates that we didn't
737 launch a new process, but connected to the running one (this can only
738 happen when using DDE under Windows for command execution). In particular,
739 in this case only, the calling code will not get the notification about
740 process termination.
741
742 If @a callback isn't @NULL and if execution is asynchronous,
743 wxProcess::OnTerminate() will be called when the process finishes.
744 Specifying this parameter also allows you to redirect the standard input
745 and/or output of the process being launched by calling
746 wxProcess::Redirect(). If the child process IO is redirected, under Windows
747 the process window is not shown by default (this avoids having to flush an
748 unnecessary console for the processes which don't create any windows
749 anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
750 happening, i.e. with this flag the child process window will be shown
751 normally.
752
753 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
754 the new process is a group leader (this will create a new session if
755 needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
756 well as all of its children (except those which have started their own
757 session).
758
759 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
760 place while the child process is running. It should be only used for very
761 short-lived processes as otherwise the application windows risk becoming
762 unresponsive from the users point of view. As this flag only makes sense
763 with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
764 flags is provided as a convenience.
765
766 @note Currently wxExecute() can only be used from the main thread, calling
767 this function from another thread will result in an assert failure in
768 debug build and won't work.
769
770 @param command
771 The command to execute and any parameters to pass to it as a single
772 string, i.e. "emacs file.txt".
773 @param flags
774 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
775 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
776 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
777 their combination, in wxEXEC_SYNC case.
778 @param callback
779 An optional pointer to wxProcess.
780
781 @see wxShell(), wxProcess, @ref page_samples_exec
782
783 @header{wx/utils.h}
784
785 @beginWxPerlOnly
786 This function is called @c Wx::ExecuteStdoutStderr and it only takes the
787 @a command argument, and returns a 3-element list (@c status, @c output,
788 @c errors), where @c output and @c errors are array references.
789 @endWxPerlOnly
790 */
791 long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
792 wxProcess* callback = NULL);
793
794 //@}
795
796 /** @ingroup group_funcmacro_procctrl */
797 //@{
798 /**
799 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
800 please see its documentation for general information.
801
802 This version takes an array of values: a command, any number of arguments,
803 terminated by @NULL.
804
805 @param argv
806 The command to execute should be the first element of this array, any
807 additional ones are the command parameters and the array must be
808 terminated with a @NULL pointer.
809 @param flags
810 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
811 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
812 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
813 their combination, in wxEXEC_SYNC case.
814 @param callback
815 An optional pointer to wxProcess.
816
817 @header{wx/utils.h}
818 */
819 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
820 wxProcess* callback = NULL);
821 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
822 wxProcess* callback = NULL);
823 //@}
824
825 /** @ingroup group_funcmacro_procctrl */
826 //@{
827
828 /**
829 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
830 please see its documentation for general information.
831
832 This version can be used to execute a process (always synchronously, the
833 contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
834 the array @e output.
835
836 @param command
837 The command to execute and any parameters to pass to it as a single
838 string.
839 @param flags
840 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
841 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
842 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
843 their combination, in wxEXEC_SYNC case.
844
845 @header{wx/utils.h}
846 */
847 long wxExecute(const wxString& command, wxArrayString& output,
848 int flags = 0);
849
850 /**
851 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
852 please see its documentation for general information.
853
854 This version adds the possibility to additionally capture the messages from
855 standard error output in the @a errors array.
856
857 @param command
858 The command to execute and any parameters to pass to it as a single
859 string.
860 @param flags
861 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
862 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
863 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
864 their combination, in wxEXEC_SYNC case.
865
866 @header{wx/utils.h}
867 */
868 long wxExecute(const wxString& command, wxArrayString& output,
869 wxArrayString& errors, int flags = 0);
870
871 /**
872 Returns the number uniquely identifying the current process in the system.
873 If an error occurs, 0 is returned.
874
875 @header{wx/utils.h}
876 */
877 unsigned long wxGetProcessId();
878
879 /**
880 Equivalent to the Unix kill function: send the given signal @a sig to the
881 process with PID @a pid. The valid signal values are:
882
883 @code
884 enum wxSignal
885 {
886 wxSIGNONE = 0, // verify if the process exists under Unix
887 wxSIGHUP,
888 wxSIGINT,
889 wxSIGQUIT,
890 wxSIGILL,
891 wxSIGTRAP,
892 wxSIGABRT,
893 wxSIGEMT,
894 wxSIGFPE,
895 wxSIGKILL, // forcefully kill, dangerous!
896 wxSIGBUS,
897 wxSIGSEGV,
898 wxSIGSYS,
899 wxSIGPIPE,
900 wxSIGALRM,
901 wxSIGTERM // terminate the process gently
902 };
903 @endcode
904
905 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
906 both Unix and Windows but all the other signals are equivalent to
907 @c wxSIGTERM under Windows.
908
909 Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
910 it will be filled with a value of the the @c wxKillError enum:
911
912 @code
913 enum wxKillError
914 {
915 wxKILL_OK, // no error
916 wxKILL_BAD_SIGNAL, // no such signal
917 wxKILL_ACCESS_DENIED, // permission denied
918 wxKILL_NO_PROCESS, // no such process
919 wxKILL_ERROR // another, unspecified error
920 };
921 @endcode
922
923 The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
924 wxKILL_CHILDREN, in which case the child processes of this process will be
925 killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
926 have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
927 wxExecute().
928
929 @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec
930
931 @header{wx/utils.h}
932 */
933 int wxKill(long pid, int sig = wxSIGTERM,
934 wxKillError rc = NULL, int flags = 0);
935
936 /**
937 Executes a command in an interactive shell window. If no command is
938 specified, then just the shell is spawned.
939
940 @see wxExecute(), @ref page_samples_exec
941
942 @header{wx/utils.h}
943 */
944 bool wxShell(const wxString& command = NULL);
945
946 /**
947 This function shuts down or reboots the computer depending on the value of
948 the @a flags.
949
950 @note Doing this requires the corresponding access rights (superuser under
951 Unix, SE_SHUTDOWN privilege under Windows NT) and that this function
952 is only implemented under Unix and Win32.
953
954 @param flags
955 Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT
956
957 @return @true on success, @false if an error occurred.
958
959 @header{wx/utils.h}
960 */
961 bool wxShutdown(wxShutdownFlags flags);
962
963 //@}
964
965
966
967 /** @ingroup group_funcmacro_time */
968 //@{
969
970 /**
971 Sleeps for the specified number of microseconds. The microsecond resolution
972 may not, in fact, be available on all platforms (currently only Unix
973 platforms with nanosleep(2) may provide it) in which case this is the same
974 as calling wxMilliSleep() with the argument of @e microseconds/1000.
975
976 @header{wx/utils.h}
977 */
978 void wxMicroSleep(unsigned long microseconds);
979
980 /**
981 Sleeps for the specified number of milliseconds. Notice that usage of this
982 function is encouraged instead of calling usleep(3) directly because the
983 standard @e usleep() function is not MT safe.
984
985 @header{wx/utils.h}
986 */
987 void wxMilliSleep(unsigned long milliseconds);
988
989 /**
990 Returns a string representing the current date and time.
991
992 @header{wx/utils.h}
993 */
994 wxString wxNow();
995
996 /**
997 Sleeps for the specified number of seconds.
998
999 @header{wx/utils.h}
1000 */
1001 void wxSleep(int secs);
1002
1003 /**
1004 @deprecated This function is deprecated because its name is misleading:
1005 notice that the argument is in milliseconds, not microseconds.
1006 Please use either wxMilliSleep() or wxMicroSleep() depending on
1007 the resolution you need.
1008
1009 Sleeps for the specified number of milliseconds.
1010
1011 @header{wx/utils.h}
1012 */
1013 void wxUsleep(unsigned long milliseconds);
1014
1015 //@}
1016