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