]>
Commit | Line | Data |
---|---|---|
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 | 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 | /** |
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 | 75 | class wxBusyCursor |
23324ae1 FM |
76 | { |
77 | public: | |
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 | */ | |
109 | void 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 | */ | |
119 | void 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 | */ | |
129 | bool 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 | */ | |
138 | void 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 | */ | |
151 | void 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 | */ | |
170 | typedef 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 | */ | |
181 | wxChar* 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 | */ | |
193 | bool 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 | */ | |
220 | bool 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 | */ | |
231 | bool 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 | */ | |
248 | bool 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 | 265 | wxBatteryState 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 | 275 | wxPowerType 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 | */ | |
284 | wxString 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 | 298 | bool 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 | 305 | wxPoint 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 | 315 | wxMouseState 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 | 323 | void 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 | 331 | wxWindow* 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 |
344 | wxWindow* 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 | 359 | wxWindow* 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 |
366 | int 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 | 379 | long 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 | */ | |
387 | void 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 | 401 | bool 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 | 435 | bool 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 |
454 | wxString 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 | 468 | void wxPostDelete(wxObject* object); |
39fb8056 | 469 | |
ea11aeee RR |
470 | |
471 | /** | |
472 | Compare function type for use with wxQsort() | |
473 | ||
474 | @header{wx/utils.h} | |
475 | */ | |
476 | extern "C" | |
477 | { | |
478 | typedef 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 | */ | |
487 | void 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 | 501 | void 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 |
517 | wxString 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 | */ | |
534 | wxString 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 |
546 | bool 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 | */ | |
554 | wxMemorySize wxGetFreeMemory(); | |
555 | ||
556 | /** | |
557 | Return the (current) user's home directory. | |
558 | ||
559 | @see wxGetUserHome(), wxStandardPaths | |
560 | ||
561 | @header{wx/utils.h} | |
562 | */ | |
563 | wxString 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 | */ | |
580 | wxString 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 | */ | |
592 | bool 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 | 602 | wxString 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 | 613 | wxString 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 | 628 | wxString 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 | 640 | bool 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 | 655 | wxString 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 | 667 | bool 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 | 678 | wxString 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 | 714 | wxOperatingSystemId 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 | 730 | bool 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 | 740 | bool 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 | */ | |
757 | wxLinuxDistributionInfo 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 | */ | |
776 | struct 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 | */ | |
875 | long 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 | */ |
914 | long wxExecute(char** argv, int flags = wxEXEC_ASYNC, | |
164db92c VZ |
915 | wxProcess* callback = NULL, |
916 | const wxExecuteEnv *env = NULL); | |
3950d49c | 917 | long 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 |
958 | long 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 | 996 | long 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 | */ |
1006 | unsigned 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 |
1064 | int 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 |
1075 | bool 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 | 1096 | bool 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 | */ | |
1113 | void 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 | */ | |
1122 | void wxMilliSleep(unsigned long milliseconds); | |
1123 | ||
1124 | /** | |
1125 | Returns a string representing the current date and time. | |
1126 | ||
1127 | @header{wx/utils.h} | |
1128 | */ | |
1129 | wxString wxNow(); | |
1130 | ||
39fb8056 FM |
1131 | /** |
1132 | Sleeps for the specified number of seconds. | |
ba2874ff BP |
1133 | |
1134 | @header{wx/utils.h} | |
39fb8056 FM |
1135 | */ |
1136 | void 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 |
1148 | void wxUsleep(unsigned long milliseconds); |
1149 | ||
1150 | //@} | |
39fb8056 | 1151 |