]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: utils.h | |
e54c96f1 | 3 | // Purpose: interface of wxWindowDisabler |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxWindowDisabler | |
11 | @wxheader{utils.h} | |
7c913512 | 12 | |
23324ae1 FM |
13 | This class disables all windows of the application (may be with the exception |
14 | of one of them) in its constructor and enables them back in its 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 FM |
19 | @library{wxcore} |
20 | @category{FIXME} | |
7c913512 | 21 | |
e54c96f1 | 22 | @see wxBusyCursor |
23324ae1 | 23 | */ |
7c913512 | 24 | class wxWindowDisabler |
23324ae1 FM |
25 | { |
26 | public: | |
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 | /** |
7c913512 | 38 | Disables all top level windows of the applications with the exception of |
4cc4bfaf | 39 | @a winToSkip if it is not @NULL. |
23324ae1 | 40 | */ |
2ecd1756 | 41 | wxWindowDisabler(wxWindow* winToSkip); |
23324ae1 FM |
42 | |
43 | /** | |
44 | Reenables back the windows disabled by the constructor. | |
45 | */ | |
46 | ~wxWindowDisabler(); | |
47 | }; | |
48 | ||
49 | ||
e54c96f1 | 50 | |
23324ae1 FM |
51 | /** |
52 | @class wxBusyCursor | |
53 | @wxheader{utils.h} | |
7c913512 | 54 | |
23324ae1 FM |
55 | This class makes it easy to tell your user that the program is temporarily busy. |
56 | Just create a wxBusyCursor object on the stack, and within the current scope, | |
57 | the hourglass will be shown. | |
7c913512 | 58 | |
23324ae1 | 59 | For example: |
7c913512 | 60 | |
23324ae1 FM |
61 | @code |
62 | wxBusyCursor wait; | |
7c913512 | 63 | |
23324ae1 FM |
64 | for (int i = 0; i 100000; i++) |
65 | DoACalculation(); | |
66 | @endcode | |
7c913512 | 67 | |
e54c96f1 FM |
68 | It works by calling wxBeginBusyCursor() in the constructor, |
69 | and wxEndBusyCursor() in the destructor. | |
7c913512 | 70 | |
23324ae1 FM |
71 | @library{wxcore} |
72 | @category{FIXME} | |
7c913512 | 73 | |
e54c96f1 | 74 | @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler |
23324ae1 | 75 | */ |
7c913512 | 76 | class wxBusyCursor |
23324ae1 FM |
77 | { |
78 | public: | |
79 | /** | |
e54c96f1 | 80 | Constructs a busy cursor object, calling wxBeginBusyCursor(). |
23324ae1 FM |
81 | */ |
82 | wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); | |
83 | ||
84 | /** | |
e54c96f1 | 85 | Destroys the busy cursor object, calling wxEndBusyCursor(). |
23324ae1 FM |
86 | */ |
87 | ~wxBusyCursor(); | |
88 | }; | |
89 | ||
90 | ||
e54c96f1 | 91 | |
23324ae1 FM |
92 | // ============================================================================ |
93 | // Global functions/macros | |
94 | // ============================================================================ | |
95 | ||
ba2874ff BP |
96 | |
97 | /** @ingroup group_funcmacro_dialog */ | |
98 | //@{ | |
99 | ||
100 | /** | |
101 | Changes the cursor to the given cursor for all windows in the application. | |
102 | Use wxEndBusyCursor() to revert the cursor back to its previous state. | |
103 | These two calls can be nested, and a counter ensures that only the outer | |
104 | calls take effect. | |
105 | ||
106 | @see wxIsBusy(), wxBusyCursor | |
107 | ||
108 | @header{wx/utils.h} | |
109 | */ | |
110 | void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); | |
111 | ||
112 | /** | |
113 | Changes the cursor back to the original cursor, for all windows in the | |
114 | application. Use with wxBeginBusyCursor(). | |
115 | ||
116 | @see wxIsBusy(), wxBusyCursor | |
117 | ||
118 | @header{wx/utils.h} | |
119 | */ | |
120 | void wxEndBusyCursor(); | |
121 | ||
122 | /** | |
123 | Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor() | |
124 | calls. | |
125 | ||
126 | @see wxBusyCursor. | |
127 | ||
128 | @header{wx/utils.h} | |
129 | */ | |
130 | bool wxIsBusy(); | |
131 | ||
132 | /** | |
133 | Ring the system bell. | |
134 | ||
135 | @note This function is categorized as a GUI one and so is not thread-safe. | |
136 | ||
137 | @header{wx/utils.h} | |
138 | */ | |
139 | void wxBell(); | |
140 | ||
141 | /** | |
142 | Shows a message box with the information about the wxWidgets build used, | |
143 | including its version, most important build parameters and the version of | |
144 | the underlying GUI toolkit. This is mainly used for diagnostic purposes | |
145 | and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which | |
146 | doesn't otherwise handle this event. | |
147 | ||
148 | @wxsince{2.9.0} | |
149 | ||
150 | @header{wx/utils.h} | |
151 | */ | |
152 | void wxInfoMessageBox(wxWindow parent = NULL); | |
153 | ||
154 | //@} | |
155 | ||
156 | ||
157 | ||
1ba0de2e BP |
158 | /** @ingroup group_funcmacro_env */ |
159 | //@{ | |
160 | ||
161 | /** | |
162 | This is a macro defined as @c getenv() or its wide char version in Unicode | |
163 | mode. | |
164 | ||
165 | Note that under Win32 it may not return correct value for the variables set | |
166 | with wxSetEnv(), use wxGetEnv() function instead. | |
167 | ||
168 | @header{wx/utils.h} | |
169 | */ | |
170 | wxChar* wxGetenv(const wxString& var); | |
171 | ||
172 | /** | |
173 | Returns the current value of the environment variable @c var in @c value. | |
174 | @c value may be @NULL if you just want to know if the variable exists and | |
175 | are not interested in its value. | |
176 | ||
177 | Returns @true if the variable exists, @false otherwise. | |
178 | ||
179 | @header{wx/utils.h} | |
180 | */ | |
181 | bool wxGetEnv(const wxString& var, wxString* value); | |
182 | ||
183 | /** | |
184 | Sets the value of the environment variable @c var (adding it if necessary) | |
185 | to @c value. | |
186 | ||
187 | Returns @true on success. | |
188 | ||
189 | @see wxUnsetEnv() | |
190 | ||
191 | @header{wx/utils.h} | |
192 | */ | |
193 | bool wxSetEnv(const wxString& var, const wxString& value); | |
194 | ||
195 | /** | |
196 | Removes the variable @c var from the environment. wxGetEnv() will return | |
197 | @NULL after the call to this function. | |
198 | ||
199 | Returns @true on success. | |
200 | ||
201 | @header{wx/utils.h} | |
202 | */ | |
203 | bool wxUnsetEnv(const wxString& var); | |
204 | ||
205 | //@} | |
206 | ||
207 | ||
208 | ||
23324ae1 FM |
209 | /** |
210 | Returns the type of power source as one of @c wxPOWER_SOCKET, | |
211 | @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. | |
212 | @c wxPOWER_UNKNOWN is also the default on platforms where this | |
213 | feature is not implemented (currently everywhere but MS Windows). | |
ba2874ff BP |
214 | |
215 | @header{wx/utils.h} | |
23324ae1 FM |
216 | */ |
217 | wxPowerType wxGetPowerType(); | |
218 | ||
219 | //@{ | |
220 | /** | |
221 | This function returns the "user id" also known as "login name" under Unix i.e. | |
222 | something like "jsmith". It uniquely identifies the current user (on this | |
223 | system). | |
23324ae1 FM |
224 | Under Windows or NT, this function first looks in the environment |
225 | variables USER and LOGNAME; if neither of these is found, the entry @b UserId | |
226 | in the @b wxWidgets section of the WIN.INI file is tried. | |
23324ae1 FM |
227 | The first variant of this function returns the login name if successful or an |
228 | empty string otherwise. The second (deprecated) function returns @true | |
229 | if successful, @false otherwise. | |
7c913512 | 230 | |
e54c96f1 | 231 | @see wxGetUserName() |
ba2874ff BP |
232 | |
233 | @header{wx/utils.h} | |
23324ae1 FM |
234 | */ |
235 | wxString wxGetUserId(); | |
4cc4bfaf | 236 | bool wxGetUserId(char* buf, int sz); |
23324ae1 FM |
237 | //@} |
238 | ||
239 | /** | |
240 | @b NB: This function is now obsolete, please use | |
e54c96f1 | 241 | wxLogFatalError() instead. |
4cc4bfaf | 242 | Displays @a msg and exits. This writes to standard error under Unix, |
23324ae1 | 243 | and pops up a message box under Windows. Used for fatal internal |
e54c96f1 | 244 | wxWidgets errors. See also wxError(). |
ba2874ff BP |
245 | |
246 | @header{wx/utils.h} | |
23324ae1 FM |
247 | */ |
248 | void wxFatalError(const wxString& msg, | |
249 | const wxString& title = "wxWidgets Fatal Error"); | |
250 | ||
251 | /** | |
252 | Returns battery state as one of @c wxBATTERY_NORMAL_STATE, | |
253 | @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, | |
254 | @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. | |
255 | @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where | |
256 | this feature is not implemented (currently everywhere but MS Windows). | |
ba2874ff BP |
257 | |
258 | @header{wx/utils.h} | |
23324ae1 FM |
259 | */ |
260 | wxBatteryState wxGetBatteryState(); | |
261 | ||
262 | /** | |
263 | @b NB: This function is obsolete, please use | |
264 | wxWindow::FindWindowByName instead. | |
23324ae1 FM |
265 | Find a window by its name (as given in a window constructor or @b Create |
266 | function call). | |
4cc4bfaf | 267 | If @a parent is @NULL, the search will start from all top-level |
23324ae1 FM |
268 | frames and dialog boxes; if non-@NULL, the search will be limited to the given |
269 | window hierarchy. | |
270 | The search is recursive in both cases. | |
23324ae1 | 271 | If no such named window is found, @b wxFindWindowByLabel is called. |
ba2874ff BP |
272 | |
273 | @header{wx/utils.h} | |
23324ae1 | 274 | */ |
4cc4bfaf FM |
275 | wxWindow* wxFindWindowByName(const wxString& name, |
276 | wxWindow* parent = NULL); | |
23324ae1 | 277 | |
23324ae1 FM |
278 | /** |
279 | This function is deprecated as the ids generated by it can conflict with the | |
280 | ids defined by the user code, use @c wxID_ANY to assign ids which are | |
281 | guaranteed to not conflict with the user-defined ids for the controls and menu | |
282 | items you create instead of using this function. | |
4cc4bfaf | 283 | |
23324ae1 | 284 | Generates an integer identifier unique to this run of the program. |
ba2874ff BP |
285 | |
286 | @header{wx/utils.h} | |
23324ae1 FM |
287 | */ |
288 | long wxNewId(); | |
289 | ||
290 | /** | |
291 | Ensures that ids subsequently generated by @b NewId do not clash with | |
292 | the given @b id. | |
ba2874ff BP |
293 | |
294 | @header{wx/utils.h} | |
23324ae1 FM |
295 | */ |
296 | void wxRegisterId(long id); | |
297 | ||
298 | /** | |
299 | @b NB: This function is now obsolete, replaced by Log | |
e54c96f1 | 300 | functions() and wxLogDebug() in particular. |
23324ae1 FM |
301 | Display a debugging message; under Windows, this will appear on the |
302 | debugger command window, and under Unix, it will be written to standard | |
303 | error. | |
23324ae1 FM |
304 | The syntax is identical to @b printf: pass a format string and a |
305 | variable list of arguments. | |
23324ae1 FM |
306 | @b Tip: under Windows, if your application crashes before the |
307 | message appears in the debugging window, put a wxYield call after | |
308 | each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s | |
309 | (at least for Watcom C++): preformat your messages and use OutputDebugString | |
310 | instead. | |
ba2874ff BP |
311 | |
312 | @header{wx/utils.h} | |
23324ae1 FM |
313 | */ |
314 | void wxDebugMsg(const wxString& fmt, ... ); | |
315 | ||
316 | /** | |
317 | For normal keys, returns @true if the specified key is currently down. | |
23324ae1 FM |
318 | For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns |
319 | @true if the key is toggled such that its LED indicator is lit. There is | |
320 | currently no way to test whether togglable keys are up or down. | |
23324ae1 FM |
321 | Even though there are virtual key codes defined for mouse buttons, they |
322 | cannot be used with this function currently. | |
ba2874ff BP |
323 | |
324 | @header{wx/utils.h} | |
23324ae1 FM |
325 | */ |
326 | bool wxGetKeyState(wxKeyCode key); | |
327 | ||
328 | /** | |
329 | Returns the string containing the description of the current platform in a | |
330 | user-readable form. For example, this function may return strings like | |
331 | @c Windows NT Version 4.0 or @c Linux 2.2.2 i386. | |
7c913512 | 332 | |
4cc4bfaf | 333 | @see ::wxGetOsVersion |
ba2874ff BP |
334 | |
335 | @header{wx/utils.h} | |
23324ae1 FM |
336 | */ |
337 | wxString wxGetOsDescription(); | |
338 | ||
339 | /** | |
340 | Return the (current) user's home directory. | |
7c913512 | 341 | |
e54c96f1 | 342 | @see wxGetUserHome(), wxStandardPaths |
ba2874ff BP |
343 | |
344 | @header{wx/utils.h} | |
23324ae1 FM |
345 | */ |
346 | wxString wxGetHomeDir(); | |
347 | ||
348 | /** | |
349 | Sleeps for the specified number of milliseconds. Notice that usage of this | |
350 | function is encouraged instead of calling usleep(3) directly because the | |
351 | standard usleep() function is not MT safe. | |
ba2874ff BP |
352 | |
353 | @header{wx/utils.h} | |
23324ae1 FM |
354 | */ |
355 | void wxMilliSleep(unsigned long milliseconds); | |
356 | ||
357 | /** | |
358 | Sleeps for the specified number of microseconds. The microsecond resolution may | |
359 | not, in fact, be available on all platforms (currently only Unix platforms with | |
360 | nanosleep(2) may provide it) in which case this is the same as | |
e54c96f1 | 361 | wxMilliSleep()(@e microseconds/1000). |
ba2874ff BP |
362 | |
363 | @header{wx/utils.h} | |
23324ae1 FM |
364 | */ |
365 | void wxMicroSleep(unsigned long microseconds); | |
366 | ||
23324ae1 | 367 | |
39fb8056 FM |
368 | /** |
369 | Find a menu item identifier associated with the given frame's menu bar. | |
ba2874ff BP |
370 | |
371 | @header{wx/utils.h} | |
39fb8056 FM |
372 | */ |
373 | int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, | |
374 | const wxString& itemString); | |
375 | ||
376 | /** | |
377 | This function enables or disables all top level windows. It is used by | |
378 | ::wxSafeYield. | |
ba2874ff BP |
379 | |
380 | @header{wx/utils.h} | |
39fb8056 FM |
381 | */ |
382 | void wxEnableTopLevelWindows(bool enable = true); | |
383 | ||
384 | /** | |
385 | Strips any menu codes from @a str and returns the result. | |
386 | By default, the functions strips both the mnemonics character (@c '') | |
387 | which is used to indicate a keyboard shortkey, and the accelerators, which are | |
388 | used only in the menu items and are separated from the main text by the | |
389 | @c \t (TAB) character. By using @a flags of | |
390 | @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former | |
391 | or the latter part, respectively. | |
392 | Notice that in most cases | |
393 | wxMenuItem::GetLabelFromText or | |
394 | wxControl::GetLabelText can be used instead. | |
ba2874ff BP |
395 | |
396 | @header{wx/utils.h} | |
39fb8056 FM |
397 | */ |
398 | wxString wxStripMenuCodes(const wxString& str, | |
399 | int flags = wxStrip_All); | |
400 | ||
401 | /** | |
402 | @b NB: This function is now obsolete, please use wxLogError() | |
403 | instead. | |
404 | Displays @a msg and continues. This writes to standard error under | |
405 | Unix, and pops up a message box under Windows. Used for internal | |
406 | wxWidgets errors. See also wxFatalError(). | |
ba2874ff BP |
407 | |
408 | @header{wx/utils.h} | |
39fb8056 FM |
409 | */ |
410 | void wxError(const wxString& msg, | |
411 | const wxString& title = "wxWidgets Internal Error"); | |
412 | ||
413 | /** | |
414 | Open the @a url in user's default browser. If @a flags parameter contains | |
415 | @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL | |
416 | (currently this is only supported under Windows). The @a url may also be a | |
417 | local file path (with or without @c file:// prefix), if it doesn't | |
418 | correspond to an existing file and the URL has no scheme @c http:// is | |
419 | prepended to it by default. | |
420 | Returns @true if the application was successfully launched. | |
421 | Note that for some configurations of the running user, the application which | |
422 | is launched to open the given URL may be URL-dependent (e.g. a browser may be | |
423 | used for | |
424 | local URLs while another one may be used for remote URLs). | |
ba2874ff BP |
425 | |
426 | @header{wx/utils.h} | |
39fb8056 FM |
427 | */ |
428 | bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); | |
429 | ||
430 | /** | |
431 | Executes a command in an interactive shell window. If no command is | |
432 | specified, then just the shell is spawned. | |
433 | See also wxExecute(), @ref overview_sampleexec "Exec sample". | |
ba2874ff BP |
434 | |
435 | @header{wx/utils.h} | |
39fb8056 FM |
436 | */ |
437 | bool wxShell(const wxString& command = NULL); | |
438 | ||
439 | /** | |
440 | Gets the version and the operating system ID for currently running OS. | |
441 | See wxPlatformInfo for more details about wxOperatingSystemId. | |
442 | ||
443 | @see ::wxGetOsDescription, wxPlatformInfo | |
ba2874ff BP |
444 | |
445 | @header{wx/utils.h} | |
39fb8056 FM |
446 | */ |
447 | wxOperatingSystemId wxGetOsVersion(int* major = NULL, | |
448 | int* minor = NULL); | |
449 | ||
450 | /** | |
451 | Returns the FQDN (fully qualified domain host name) or an empty string on | |
452 | error. | |
453 | ||
454 | @see wxGetHostName() | |
39fb8056 | 455 | |
ba2874ff | 456 | @header{wx/utils.h} |
39fb8056 | 457 | */ |
ba2874ff | 458 | wxString wxGetFullHostName(); |
39fb8056 FM |
459 | |
460 | /** | |
461 | Tells the system to delete the specified object when | |
462 | all other events have been processed. In some environments, it is | |
463 | necessary to use this instead of deleting a frame directly with the | |
464 | delete operator, because some GUIs will still send events to a deleted window. | |
465 | Now obsolete: use wxWindow::Close instead. | |
ba2874ff BP |
466 | |
467 | @header{wx/utils.h} | |
39fb8056 FM |
468 | */ |
469 | void wxPostDelete(wxObject* object); | |
470 | ||
471 | /** | |
472 | @b NB: This function is obsolete, please use | |
473 | wxWindow::FindWindowByLabel instead. | |
474 | Find a window by its label. Depending on the type of window, the label may be a | |
475 | window title | |
476 | or panel item label. If @a parent is @NULL, the search will start from all | |
477 | top-level | |
478 | frames and dialog boxes; if non-@NULL, the search will be limited to the given | |
479 | window hierarchy. | |
480 | The search is recursive in both cases. | |
ba2874ff BP |
481 | |
482 | @header{wx/utils.h} | |
39fb8056 FM |
483 | */ |
484 | wxWindow* wxFindWindowByLabel(const wxString& label, | |
485 | wxWindow* parent = NULL); | |
486 | ||
487 | ||
488 | /** | |
489 | Returns the mouse position in screen coordinates. | |
ba2874ff BP |
490 | |
491 | @header{wx/utils.h} | |
39fb8056 FM |
492 | */ |
493 | wxPoint wxGetMousePosition(); | |
494 | ||
495 | /** | |
496 | Loads a user-defined Windows resource as a string. If the resource is found, | |
497 | the function creates | |
498 | a new character array and copies the data into it. A pointer to this data is | |
499 | returned. If unsuccessful, @NULL is returned. | |
500 | The resource must be defined in the @c .rc file using the following syntax: | |
501 | ||
502 | @code | |
503 | myResource TEXT file.ext | |
504 | @endcode | |
505 | ||
506 | where @c file.ext is a file that the resource compiler can find. | |
507 | This function is available under Windows only. | |
ba2874ff BP |
508 | |
509 | @header{wx/utils.h} | |
39fb8056 FM |
510 | */ |
511 | wxString wxLoadUserResource(const wxString& resourceName, | |
512 | const wxString& resourceType = "TEXT"); | |
513 | ||
514 | /** | |
515 | Returns the amount of free memory in bytes under environments which | |
516 | support it, and -1 if not supported or failed to perform measurement. | |
517 | */ | |
518 | wxMemorySize wxGetFreeMemory(); | |
519 | ||
23324ae1 | 520 | //@{ |
39fb8056 FM |
521 | /** |
522 | Copies the current host machine's name into the supplied buffer. Please note | |
523 | that the returned name is @e not fully qualified, i.e. it does not include | |
524 | the domain name. | |
525 | Under Windows or NT, this function first looks in the environment | |
526 | variable SYSTEM_NAME; if this is not found, the entry @b HostName | |
527 | in the @b wxWidgets section of the WIN.INI file is tried. | |
528 | The first variant of this function returns the hostname if successful or an | |
529 | empty string otherwise. The second (deprecated) function returns @true | |
530 | if successful, @false otherwise. | |
531 | ||
532 | @see wxGetFullHostName() | |
ba2874ff BP |
533 | |
534 | @header{wx/utils.h} | |
39fb8056 FM |
535 | */ |
536 | wxString wxGetHostName(); | |
537 | bool wxGetHostName(char* buf, int sz); | |
23324ae1 FM |
538 | //@} |
539 | ||
39fb8056 FM |
540 | /** |
541 | Under X only, returns the current display name. See also wxSetDisplayName(). | |
39fb8056 | 542 | |
ba2874ff | 543 | @header{wx/utils.h} |
39fb8056 | 544 | */ |
ba2874ff | 545 | wxString wxGetDisplayName(); |
39fb8056 FM |
546 | |
547 | /** | |
548 | Returns the home directory for the given user. If the @a user is empty | |
549 | (default value), this function behaves like | |
550 | wxGetHomeDir() i.e. returns the current user home | |
551 | directory. | |
552 | If the home directory couldn't be determined, an empty string is returned. | |
ba2874ff BP |
553 | |
554 | @header{wx/utils.h} | |
39fb8056 FM |
555 | */ |
556 | wxString wxGetUserHome(const wxString& user = ""); | |
23324ae1 FM |
557 | |
558 | //@{ | |
39fb8056 FM |
559 | /** |
560 | @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr | |
561 | and it only takes the @c command argument, | |
562 | and returns a 3-element list @c ( status, output, errors ), where | |
563 | @c output and @c errors are array references. | |
564 | Executes another program in Unix or Windows. | |
565 | The first form takes a command string, such as @c "emacs file.txt". | |
566 | The second form takes an array of values: a command, any number of | |
567 | arguments, terminated by @NULL. | |
568 | The semantics of the third and fourth versions is different from the first two | |
569 | and is described in more details below. | |
570 | If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow | |
571 | of control immediately returns. If it contains @c wxEXEC_SYNC, the current | |
572 | application waits until the other program has terminated. | |
573 | In the case of synchronous execution, the return value is the exit code of | |
574 | the process (which terminates by the moment the function returns) and will be | |
575 | -1 if the process couldn't be started and typically 0 if the process | |
576 | terminated successfully. Also, while waiting for the process to | |
577 | terminate, wxExecute will call wxYield(). Because of this, by | |
578 | default this function disables all application windows to avoid unexpected | |
579 | reentrancies which could result from the users interaction with the program | |
580 | while the child process is running. If you are sure that it is safe to not | |
581 | disable the program windows, you may pass @c wxEXEC_NODISABLE flag to | |
582 | prevent this automatic disabling from happening. | |
583 | For asynchronous execution, however, the return value is the process id and | |
584 | zero value indicates that the command could not be executed. As an added | |
585 | complication, the return value of -1 in this case indicates that we didn't | |
586 | launch a new process, but connected to the running one (this can only happen in | |
587 | case of using DDE under Windows for command execution). In particular, in this, | |
588 | and only this, case the calling code will not get the notification about | |
589 | process termination. | |
590 | If callback isn't @NULL and if execution is asynchronous, | |
591 | wxProcess::OnTerminate will be called when | |
592 | the process finishes. Specifying this parameter also allows you to redirect the | |
593 | standard input and/or output of the process being launched by calling | |
594 | wxProcess::Redirect. If the child process IO is redirected, | |
595 | under Windows the process window is not shown by default (this avoids having to | |
596 | flush an unnecessary console for the processes which don't create any windows | |
597 | anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from | |
598 | happening, i.e. with this flag the child process window will be shown normally. | |
599 | Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure | |
600 | that the new process is a group leader (this will create a new session if | |
601 | needed). Calling wxKill() passing wxKILL_CHILDREN will | |
602 | kill this process as well as all of its children (except those which have | |
603 | started their own session). | |
604 | The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking | |
605 | place while the child process is running. It should be only used for very | |
606 | short-lived processes as otherwise the application windows risk becoming | |
607 | unresponsive from the users point of view. As this flag only makes sense with | |
608 | @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags | |
609 | is provided as a convenience. | |
610 | Finally, you may use the third overloaded version of this function to execute | |
611 | a process (always synchronously, the contents of @a flags is or'd with | |
612 | @c wxEXEC_SYNC) and capture its output in the array @e output. The | |
613 | fourth version adds the possibility to additionally capture the messages from | |
614 | standard error output in the @a errors array. | |
615 | @b NB: Currently wxExecute() can only be used from the main thread, calling | |
616 | this function from another thread will result in an assert failure in debug | |
617 | build and won't work. | |
618 | ||
619 | @param command | |
620 | The command to execute and any parameters to pass to it as a | |
621 | single string. | |
622 | @param argv | |
623 | The command to execute should be the first element of this | |
624 | array, any additional ones are the command parameters and the array must be | |
625 | terminated with a @NULL pointer. | |
626 | @param flags | |
627 | Combination of bit masks wxEXEC_ASYNC, | |
628 | wxEXEC_SYNC and wxEXEC_NOHIDE | |
629 | @param callback | |
630 | An optional pointer to wxProcess | |
631 | ||
632 | @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample". | |
ba2874ff BP |
633 | |
634 | @header{wx/utils.h} | |
39fb8056 FM |
635 | */ |
636 | long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, | |
637 | wxProcess* callback = NULL); | |
638 | wxPerl note: long wxExecute(char** argv, | |
639 | int flags = wxEXEC_ASYNC, | |
640 | wxProcess* callback = NULL); | |
641 | wxPerl note: long wxExecute(const wxString& command, | |
642 | wxArrayString& output, | |
643 | int flags = 0); | |
644 | wxPerl note: long wxExecute(const wxString& command, | |
645 | wxArrayString& output, | |
646 | wxArrayString& errors, | |
647 | int flags = 0); | |
23324ae1 FM |
648 | //@} |
649 | ||
39fb8056 FM |
650 | /** |
651 | Returns a string representing the current date and time. | |
ba2874ff BP |
652 | |
653 | @header{wx/utils.h} | |
39fb8056 FM |
654 | */ |
655 | wxString wxNow(); | |
656 | ||
657 | /** | |
658 | Returns @true if the operating system the program is running under is 64 bit. | |
659 | The check is performed at run-time and may differ from the value available at | |
660 | compile-time (at compile-time you can just check if @c sizeof(void*)==8) | |
661 | since the program could be running in emulation mode or in a mixed 32/64 bit | |
662 | system | |
663 | (bi-architecture operating system). | |
664 | Very important: this function is not 100% reliable on some systems given the | |
665 | fact | |
666 | that there isn't always a standard way to do a reliable check on the OS | |
667 | architecture. | |
ba2874ff BP |
668 | |
669 | @header{wx/utils.h} | |
39fb8056 FM |
670 | */ |
671 | bool wxIsPlatform64Bit(); | |
672 | ||
673 | /** | |
674 | Returns the number uniquely identifying the current process in the system. | |
675 | If an error occurs, 0 is returned. | |
ba2874ff BP |
676 | |
677 | @header{wx/utils.h} | |
39fb8056 FM |
678 | */ |
679 | unsigned long wxGetProcessId(); | |
680 | ||
681 | /** | |
682 | Equivalent to the Unix kill function: send the given signal @a sig to the | |
683 | process with PID @e pid. The valid signal values are | |
684 | ||
685 | @code | |
686 | enum wxSignal | |
687 | { | |
688 | wxSIGNONE = 0, // verify if the process exists under Unix | |
689 | wxSIGHUP, | |
690 | wxSIGINT, | |
691 | wxSIGQUIT, | |
692 | wxSIGILL, | |
693 | wxSIGTRAP, | |
694 | wxSIGABRT, | |
695 | wxSIGEMT, | |
696 | wxSIGFPE, | |
697 | wxSIGKILL, // forcefully kill, dangerous! | |
698 | wxSIGBUS, | |
699 | wxSIGSEGV, | |
700 | wxSIGSYS, | |
701 | wxSIGPIPE, | |
702 | wxSIGALRM, | |
703 | wxSIGTERM // terminate the process gently | |
704 | }; | |
705 | @endcode | |
706 | ||
707 | @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning | |
708 | under both Unix and Windows but all the other signals are equivalent to | |
709 | @c wxSIGTERM under Windows. | |
710 | Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will | |
711 | be filled with an element of @c wxKillError enum: | |
712 | ||
713 | @code | |
714 | enum wxKillError | |
715 | { | |
716 | wxKILL_OK, // no error | |
717 | wxKILL_BAD_SIGNAL, // no such signal | |
718 | wxKILL_ACCESS_DENIED, // permission denied | |
719 | wxKILL_NO_PROCESS, // no such process | |
720 | wxKILL_ERROR // another, unspecified error | |
721 | }; | |
722 | @endcode | |
723 | ||
724 | The @a flags parameter can be wxKILL_NOCHILDREN (the default), | |
725 | or wxKILL_CHILDREN, in which case the child processes of this | |
726 | process will be killed too. Note that under Unix, for wxKILL_CHILDREN | |
727 | to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER | |
728 | to wxExecute. | |
729 | ||
730 | @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" | |
ba2874ff BP |
731 | |
732 | @header{wx/utils.h} | |
39fb8056 FM |
733 | */ |
734 | int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL, | |
735 | int flags = 0); | |
736 | ||
737 | /** | |
738 | Returns the current state of the mouse. Returns a wxMouseState | |
739 | instance that contains the current position of the mouse pointer in | |
740 | screen coordinates, as well as boolean values indicating the up/down | |
741 | status of the mouse buttons and the modifier keys. | |
39fb8056 | 742 | |
ba2874ff | 743 | @header{wx/utils.h} |
39fb8056 | 744 | */ |
ba2874ff | 745 | wxMouseState wxGetMouseState(); |
23324ae1 | 746 | |
7c913512 | 747 | //@{ |
39fb8056 FM |
748 | /** |
749 | Copies the user's email address into the supplied buffer, by | |
750 | concatenating the values returned by wxGetFullHostName() | |
751 | and wxGetUserId(). | |
752 | Returns @true if successful, @false otherwise. | |
ba2874ff BP |
753 | |
754 | @header{wx/utils.h} | |
39fb8056 FM |
755 | */ |
756 | wxString wxGetEmailAddress(); | |
757 | bool wxGetEmailAddress(char* buf, int sz); | |
7c913512 | 758 | //@} |
23324ae1 | 759 | |
39fb8056 FM |
760 | /** |
761 | Sleeps for the specified number of seconds. | |
ba2874ff BP |
762 | |
763 | @header{wx/utils.h} | |
39fb8056 FM |
764 | */ |
765 | void wxSleep(int secs); | |
766 | ||
39fb8056 FM |
767 | /** |
768 | Returns @true if the current platform is little endian (instead of big | |
769 | endian). | |
770 | The check is performed at run-time. | |
771 | ||
772 | @see @ref overview_byteordermacros "Byte order macros" | |
ba2874ff BP |
773 | |
774 | @header{wx/utils.h} | |
39fb8056 FM |
775 | */ |
776 | bool wxIsPlatformLittleEndian(); | |
777 | ||
778 | /** | |
779 | Under X only, sets the current display name. This is the X host and display | |
780 | name such | |
781 | as "colonsay:0.0", and the function indicates which display should be used for | |
782 | creating | |
783 | windows from this point on. Setting the display within an application allows | |
784 | multiple | |
785 | displays to be used. | |
786 | See also wxGetDisplayName(). | |
ba2874ff BP |
787 | |
788 | @header{wx/utils.h} | |
39fb8056 FM |
789 | */ |
790 | void wxSetDisplayName(const wxString& displayName); | |
23324ae1 | 791 |