1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: utils.h 3 // Purpose: interface of various utility classes and functions 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 Signal constants used by wxProcess. 10 */ 11 enum wxSignal 12 { 13 wxSIGNONE = 0, //!< verify if the process exists under Unix 14 wxSIGHUP, 15 wxSIGINT, 16 wxSIGQUIT, 17 wxSIGILL, 18 wxSIGTRAP, 19 wxSIGABRT, 20 wxSIGEMT, 21 wxSIGFPE, 22 wxSIGKILL, //!< forcefully kill, dangerous! 23 wxSIGBUS, 24 wxSIGSEGV, 25 wxSIGSYS, 26 wxSIGPIPE, 27 wxSIGALRM, 28 wxSIGTERM //!< terminate the process gently 29 }; 30 31 /** 32 Return values for wxProcess::Kill. 33 */ 34 enum wxKillError 35 { 36 wxKILL_OK, //!< no error 37 wxKILL_BAD_SIGNAL, //!< no such signal 38 wxKILL_ACCESS_DENIED, //!< permission denied 39 wxKILL_NO_PROCESS, //!< no such process 40 wxKILL_ERROR //!< another, unspecified error 41 }; 42 43 enum wxKillFlags 44 { 45 wxKILL_NOCHILDREN = 0, //!< don't kill children 46 wxKILL_CHILDREN = 1 //!< kill children 47 }; 48 49 enum wxShutdownFlags 50 { 51 wxSHUTDOWN_FORCE = 1, //!< can be combined with other flags (MSW-only) 52 wxSHUTDOWN_POWEROFF = 2, //!< power off the computer 53 wxSHUTDOWN_REBOOT = 4, //!< shutdown and reboot 54 wxSHUTDOWN_LOGOFF = 8 //!< close session (currently MSW-only) 55 }; 56 57 58 /** 59 @class wxWindowDisabler 60 61 This class disables all windows of the application (may be with the 62 exception of one of them) in its constructor and enables them back in its 63 destructor. 64 65 This is useful when you want to indicate to the user that the application 66 is currently busy and cannot respond to user input. 67 68 @library{wxcore} 69 @category{misc} 70 71 @see wxBusyCursor 72 */ 73 class wxWindowDisabler 74 { 75 public: 76 /** 77 Disables all top level windows of the applications. 78 79 If @a disable is @c false nothing is done. This can be convenient if 80 the windows should be disabled depending on some condition. 81 82 @since 2.9.0 83 */ 84 wxWindowDisabler(bool disable = true); 85 86 /** 87 Disables all top level windows of the applications with the exception 88 of @a winToSkip if it is not @NULL. 89 90 Notice that under MSW if @a winToSkip appears in the taskbar, the user 91 will be able to close the entire application (even though its main 92 window is disabled) by right clicking on the taskbar icon and selecting 93 the appropriate "Close" command from the context menu. To prevent this 94 from happening you may want to use wxFRAME_TOOL_WINDOW, if applicable, 95 or wxFRAME_NO_TASKBAR style when creating the window that will remain 96 enabled. 97 */ 98 wxWindowDisabler(wxWindow* winToSkip); 99 100 /** 101 Reenables the windows disabled by the constructor. 102 */ 103 ~wxWindowDisabler(); 104 }; 105 106 107 108 /** 109 @class wxBusyCursor 110 111 This class makes it easy to tell your user that the program is temporarily 112 busy. Just create a wxBusyCursor object on the stack, and within the 113 current scope, the hourglass will be shown. 114 115 For example: 116 117 @code 118 wxBusyCursor wait; 119 120 for (int i = 0; i < 100000; i++) 121 DoACalculation(); 122 @endcode 123 124 It works by calling wxBeginBusyCursor() in the constructor, and 125 wxEndBusyCursor() in the destructor. 126 127 @library{wxcore} 128 @category{misc} 129 130 @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler 131 */ 132 class wxBusyCursor 133 { 134 public: 135 /** 136 Constructs a busy cursor object, calling wxBeginBusyCursor(). 137 */ 138 wxBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR); 139 140 /** 141 Destroys the busy cursor object, calling wxEndBusyCursor(). 142 */ 143 ~wxBusyCursor(); 144 }; 145 146 147 148 // ============================================================================ 149 // Global functions/macros 150 // ============================================================================ 151 152 153 /** @addtogroup group_funcmacro_dialog */ 154 //@{ 155 156 /** 157 Changes the cursor to the given cursor for all windows in the application. 158 Use wxEndBusyCursor() to revert the cursor back to its previous state. 159 These two calls can be nested, and a counter ensures that only the outer 160 calls take effect. 161 162 @see wxIsBusy(), wxBusyCursor 163 164 @header{wx/utils.h} 165 */ 166 void wxBeginBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR); 167 168 /** 169 Changes the cursor back to the original cursor, for all windows in the 170 application. Use with wxBeginBusyCursor(). 171 172 @see wxIsBusy(), wxBusyCursor 173 174 @header{wx/utils.h} 175 */ 176 void wxEndBusyCursor(); 177 178 /** 179 Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor() 180 calls. 181 182 @see wxBusyCursor. 183 184 @header{wx/utils.h} 185 */ 186 bool wxIsBusy(); 187 188 /** 189 Ring the system bell. 190 191 @note This function is categorized as a GUI one and so is not thread-safe. 192 193 @header{wx/utils.h} 194 195 @library{wxcore} 196 */ 197 void wxBell(); 198 199 /** 200 Shows a message box with the information about the wxWidgets build used, 201 including its version, most important build parameters and the version of 202 the underlying GUI toolkit. This is mainly used for diagnostic purposes 203 and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which 204 doesn't otherwise handle this event. 205 206 @since 2.9.0 207 208 @see wxGetLibraryVersionInfo() 209 210 @header{wx/utils.h} 211 */ 212 void wxInfoMessageBox(wxWindow* parent); 213 214 //@} 215 216 /** @addtogroup group_funcmacro_version */ 217 //@{ 218 219 /** 220 Get wxWidgets version information. 221 222 @since 2.9.2 223 224 @see wxVersionInfo 225 226 @header{wx/utils.h} 227 228 @library{wxcore} 229 */ 230 wxVersionInfo wxGetLibraryVersionInfo(); 231 232 //@} 233 234 235 236 /** @addtogroup group_funcmacro_env */ 237 //@{ 238 239 /** 240 A map type containing environment variables names and values. 241 242 This type is used with wxGetEnvMap() function and wxExecuteEnv structure 243 optionally passed to wxExecute(). 244 245 @since 2.9.2 246 247 @header{wx/utils.h} 248 */ 249 typedef wxStringToStringHashMap wxEnvVariableHashMap; 250 251 /** 252 This is a macro defined as @c getenv() or its wide char version in Unicode 253 mode. 254 255 Note that under Win32 it may not return correct value for the variables set 256 with wxSetEnv(), use wxGetEnv() function instead. 257 258 @header{wx/utils.h} 259 */ 260 wxChar* wxGetenv(const wxString& var); 261 262 /** 263 Returns the current value of the environment variable @a var in @a value. 264 265 @a value may be @NULL if you just want to know if the variable exists and 266 are not interested in its value. 267 268 Returns @true if the variable exists, @false otherwise. 269 270 @header{wx/utils.h} 271 */ 272 bool wxGetEnv(const wxString& var, wxString* value); 273 274 /** 275 Sets the value of the environment variable @a var (adding it if necessary) 276 to @a value. 277 278 Notice that under Windows platforms the program may have two different 279 environment blocks: the first one is that of a Windows process and is 280 always present, but the CRT may maintain its own independent copy of the 281 environment. wxSetEnv() will always update the first copy, which means that 282 wxGetEnv(), which uses it directly, will always return the expected value 283 after this call. But wxSetEnv() only updates the second copy for some 284 compilers/CRT implementations (currently only MSVC and MinGW which uses the 285 same MSVC CRT) and so using wxGetenv() (notice the difference in case) may 286 not return the updated value. 287 288 @param var 289 The environment variable to be set, must not contain @c '=' character. 290 @param value 291 New value of the variable. 292 @return 293 @true on success or @false if changing the value failed. 294 295 @see wxUnsetEnv() 296 297 @header{wx/utils.h} 298 */ 299 bool wxSetEnv(const wxString& var, const wxString& value); 300 301 /** 302 Removes the variable @a var from the environment. 303 304 wxGetEnv() will return @NULL after the call to this function. 305 306 Returns @true on success. 307 308 @header{wx/utils.h} 309 */ 310 bool wxUnsetEnv(const wxString& var); 311 312 /** 313 Fill a map with the complete content of current environment. 314 315 The map will contain the environment variable names as keys and their 316 values as values. 317 318 @param map 319 The environment map to fill, must be non-@NULL. 320 @return 321 @true if environment was successfully retrieved or @false otherwise. 322 323 @header{wx/utils.h} 324 325 @since 2.9.2 326 */ 327 bool wxGetEnvMap(wxEnvVariableHashMap *map); 328 //@} 329 330 331 332 /** @addtogroup group_funcmacro_misc */ 333 //@{ 334 335 /** 336 Returns battery state as one of @c wxBATTERY_NORMAL_STATE, 337 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, 338 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. 339 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this 340 feature is not implemented (currently everywhere but MS Windows). 341 342 @header{wx/utils.h} 343 */ 344 wxBatteryState wxGetBatteryState(); 345 346 /** 347 Returns the type of power source as one of @c wxPOWER_SOCKET, 348 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the 349 default on platforms where this feature is not implemented (currently 350 everywhere but MS Windows). 351 352 @header{wx/utils.h} 353 */ 354 wxPowerType wxGetPowerType(); 355 356 /** 357 Under X only, returns the current display name. 358 359 @see wxSetDisplayName() 360 361 @header{wx/utils.h} 362 */ 363 wxString wxGetDisplayName(); 364 365 /** 366 For normal keys, returns @true if the specified key is currently down. 367 368 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if 369 the key is toggled such that its LED indicator is lit. There is currently 370 no way to test whether togglable keys are up or down. 371 372 Even though there are virtual key codes defined for mouse buttons, they 373 cannot be used with this function currently. 374 375 In wxGTK, this function can be only used with modifier keys (@c WXK_ALT, @c 376 WXK_CONTROL and @c WXK_SHIFT) when not using X11 backend currently. 377 378 @header{wx/utils.h} 379 */ 380 bool wxGetKeyState(wxKeyCode key); 381 382 /** 383 Returns the mouse position in screen coordinates. 384 385 @header{wx/utils.h} 386 */ 387 wxPoint wxGetMousePosition(); 388 389 /** 390 Returns the current state of the mouse. Returns a wxMouseState instance 391 that contains the current position of the mouse pointer in screen 392 coordinates, as well as boolean values indicating the up/down status of the 393 mouse buttons and the modifier keys. 394 395 @header{wx/utils.h} 396 */ 397 wxMouseState wxGetMouseState(); 398 399 /** 400 This function enables or disables all top level windows. It is used by 401 wxSafeYield(). 402 403 @header{wx/utils.h} 404 */ 405 void wxEnableTopLevelWindows(bool enable = true); 406 407 /** 408 Find the deepest window at the given mouse position in screen coordinates, 409 returning the window if found, or @NULL if not. 410 411 This function takes child windows at the given position into account even 412 if they are disabled. The hidden children are however skipped by it. 413 414 @header{wx/utils.h} 415 */ 416 wxWindow* wxFindWindowAtPoint(const wxPoint& pt); 417 418 /** 419 @deprecated Replaced by wxWindow::FindWindowByLabel(). 420 421 Find a window by its label. Depending on the type of window, the label may 422 be a window title or panel item label. If @a parent is @NULL, the search 423 will start from all top-level frames and dialog boxes; if non-@NULL, the 424 search will be limited to the given window hierarchy. The search is 425 recursive in both cases. 426 427 @header{wx/utils.h} 428 */ 429 wxWindow* wxFindWindowByLabel(const wxString& label, 430 wxWindow* parent = NULL); 431 432 /** 433 @deprecated Replaced by wxWindow::FindWindowByName(). 434 435 Find a window by its name (as given in a window constructor or @e Create 436 function call). If @a parent is @NULL, the search will start from all 437 top-level frames and dialog boxes; if non-@NULL, the search will be limited 438 to the given window hierarchy. The search is recursive in both cases. 439 440 If no such named window is found, wxFindWindowByLabel() is called. 441 442 @header{wx/utils.h} 443 */ 444 wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL); 445 446 /** 447 Find a menu item identifier associated with the given frame's menu bar. 448 449 @header{wx/utils.h} 450 */ 451 int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, 452 const wxString& itemString); 453 454 /** 455 @deprecated Ids generated by it can conflict with the Ids defined by the 456 user code, use @c wxID_ANY to assign ids which are guaranteed 457 to not conflict with the user-defined ids for the controls and 458 menu items you create instead of using this function. 459 460 Generates an integer identifier unique to this run of the program. 461 462 @header{wx/utils.h} 463 */ 464 int wxNewId(); 465 466 /** 467 Ensures that Ids subsequently generated by wxNewId() do not clash with the 468 given @a id. 469 470 @header{wx/utils.h} 471 */ 472 void wxRegisterId(int id); 473 474 /** 475 Opens the @a document in the application associated with the files of this 476 type. 477 478 The @a flags parameter is currently not used 479 480 Returns @true if the application was successfully launched. 481 482 @see wxLaunchDefaultBrowser(), wxExecute() 483 484 @header{wx/utils.h} 485 */ 486 bool wxLaunchDefaultApplication(const wxString& document, int flags = 0); 487 488 /** 489 Opens the @a url in user's default browser. 490 491 If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new 492 window is opened for the URL (currently this is only supported under 493 Windows). 494 495 And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag, 496 a busy cursor is shown while the browser is being launched (using 497 wxBusyCursor). 498 499 The parameter @a url is interpreted as follows: 500 - if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "mailto:") 501 it is passed to the appropriate browser configured in the user system. 502 - if it has no valid scheme (e.g. it's a local file path without the @c "file:" 503 prefix), then ::wxFileExists and ::wxDirExists are used to test if it's a 504 local file/directory; if it is, then the browser is called with the 505 @a url parameter eventually prefixed by @c "file:". 506 - if it has no valid scheme and it's not a local file/directory, then @c "http:" 507 is prepended and the browser is called. 508 509 Returns @true if the application was successfully launched. 510 511 @note For some configurations of the running user, the application which is 512 launched to open the given URL may be URL-dependent (e.g. a browser 513 may be used for local URLs while another one may be used for remote 514 URLs). 515 516 @see wxLaunchDefaultApplication(), wxExecute() 517 518 @header{wx/utils.h} 519 */ 520 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); 521 522 /** 523 Loads an object from Windows resource file. 524 525 This function loads the resource with the given name and type from the 526 resources embedded into a Windows application. 527 528 The typical use for it is to load some data from the data files embedded 529 into the program itself. For example, you could have the following fragment 530 in your @c .rc file 531 @code 532 mydata MYDATA "myfile.dat" 533 @endcode 534 and then use it in the following way: 535 @code 536 const void* data = NULL; 537 size_t size = 0; 538 if ( !wxLoadUserResource(&data, &size, "mydata", "MYDATA") ) { 539 ... handle error ... 540 } 541 else { 542 // Use the data in any way, for example: 543 wxMemoryInputStream is(data, size); 544 ... read the data from stream ... 545 } 546 @endcode 547 548 @param outData Filled with the pointer to the data on successful return. 549 Notice that this pointer does @em not need to be freed by the caller. 550 @param outLen Filled with the length of the data in bytes. 551 @param resourceName The name of the resource to load. 552 @param resourceType The type of the resource in usual Windows format, i.e. 553 either a real string like "MYDATA" or an integer created by the 554 standard Windows @c MAKEINTRESOURCE() macro, including any constants 555 for the standard resources types like @c RT_RCDATA. 556 @param module The @c HINSTANCE of the module to load the resources from. 557 The current module is used by default. 558 @return true if the data was loaded from resource or false if it couldn't 559 be found (in which case no error is logged) or was found but couldn't 560 be loaded (which is unexpected and does result in an error message). 561 562 This function is available under Windows only. 563 564 @library{wxbase} 565 566 @header{wx/utils.h} 567 568 @since 2.9.1 569 */ 570 bool 571 wxLoadUserResource(const void **outData, 572 size_t *outLen, 573 const wxString& resourceName, 574 const wxChar* resourceType = "TEXT", 575 WXHINSTANCE module = 0); 576 577 /** 578 Loads a user-defined Windows resource as a string. 579 580 This is a wrapper for the general purpose overload wxLoadUserResource(const 581 void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be 582 more convenient for the string data, but does an extra copy compared to the 583 general version. 584 585 @param resourceName The name of the resource to load. 586 @param resourceType The type of the resource in usual Windows format, i.e. 587 either a real string like "MYDATA" or an integer created by the 588 standard Windows @c MAKEINTRESOURCE() macro, including any constants 589 for the standard resources types like @c RT_RCDATA. 590 @param pLen Filled with the length of the returned buffer if it is 591 non-@NULL. This parameter should be used if NUL characters can occur in 592 the resource data. It is new since wxWidgets 2.9.1 593 @param module The @c HINSTANCE of the module to load the resources from. 594 The current module is used by default. This parameter is new since 595 wxWidgets 2.9.1. 596 @return A pointer to the data to be <tt>delete[]</tt>d by caller on success 597 or @NULL on error. 598 599 This function is available under Windows only. 600 601 @library{wxbase} 602 603 @header{wx/utils.h} 604 */ 605 char* wxLoadUserResource(const wxString& resourceName, 606 const wxChar* resourceType = "TEXT", 607 int* pLen = NULL, 608 WXHINSTANCE module = 0); 609 610 /** 611 @deprecated Replaced by wxWindow::Close(). See the 612 @ref overview_windowdeletion "window deletion overview". 613 614 Tells the system to delete the specified object when all other events have 615 been processed. In some environments, it is necessary to use this instead 616 of deleting a frame directly with the delete operator, because some GUIs 617 will still send events to a deleted window. 618 619 @header{wx/utils.h} 620 */ 621 void wxPostDelete(wxObject* object); 622 623 624 /** 625 Compare function type for use with wxQsort() 626 627 @header{wx/utils.h} 628 */ 629 typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data); 630 631 /** 632 Function implementing quick sort algorithm. 633 634 This function sorts @a total_elems objects of size @a size located at @a 635 pbase. It uses @a cmp function for comparing them and passes @a user_data 636 pointer to the comparison function each time it's called. 637 638 @header{wx/utils.h} 639 */ 640 void wxQsort(void* pbase, size_t total_elems, 641 size_t size, wxSortCallback cmp, const void* user_data); 642 643 644 /** 645 Under X only, sets the current display name. This is the X host and display 646 name such as "colonsay:0.0", and the function indicates which display 647 should be used for creating windows from this point on. Setting the display 648 within an application allows multiple displays to be used. 649 650 @see wxGetDisplayName() 651 652 @header{wx/utils.h} 653 */ 654 void wxSetDisplayName(const wxString& displayName); 655 656 657 /** 658 flags for wxStripMenuCodes 659 */ 660 enum 661 { 662 // strip '&' characters 663 wxStrip_Mnemonics = 1, 664 665 // strip everything after '\t' 666 wxStrip_Accel = 2, 667 668 // strip everything (this is the default) 669 wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel 670 }; 671 672 /** 673 Strips any menu codes from @a str and returns the result. 674 675 By default, the functions strips both the mnemonics character (@c '&') 676 which is used to indicate a keyboard shortkey, and the accelerators, which 677 are used only in the menu items and are separated from the main text by the 678 @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or 679 @c wxStrip_Accel to strip only the former or the latter part, respectively. 680 681 Notice that in most cases wxMenuItem::GetLabelFromText() or 682 wxControl::GetLabelText() can be used instead. 683 684 @header{wx/utils.h} 685 */ 686 wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); 687 688 //@} 689 690 691 692 /** @addtogroup group_funcmacro_networkuseros */ 693 //@{ 694 695 /** 696 Copies the user's email address into the supplied buffer, by concatenating 697 the values returned by wxGetFullHostName() and wxGetUserId(). 698 699 @return @true if successful, @false otherwise. 700 701 @header{wx/utils.h} 702 */ 703 wxString wxGetEmailAddress(); 704 705 /** 706 @deprecated Use wxGetEmailAddress() instead. 707 708 @param buf Buffer to store the email address in. 709 @param sz Size of the buffer. 710 711 @return @true if successful, @false otherwise. 712 713 @header{wx/utils.h} 714 */ 715 bool wxGetEmailAddress(char* buf, int sz); 716 717 /** 718 Returns the amount of free memory in bytes under environments which support 719 it, and -1 if not supported or failed to perform measurement. 720 721 @header{wx/utils.h} 722 */ 723 wxMemorySize wxGetFreeMemory(); 724 725 /** 726 Return the (current) user's home directory. 727 728 @see wxGetUserHome(), wxStandardPaths 729 730 @header{wx/utils.h} 731 */ 732 wxString wxGetHomeDir(); 733 734 /** 735 Copies the current host machine's name into the supplied buffer. Please 736 note that the returned name is @e not fully qualified, i.e. it does not 737 include the domain name. 738 739 Under Windows or NT, this function first looks in the environment variable 740 SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets 741 section of the WIN.INI file is tried. 742 743 @return The hostname if successful or an empty string otherwise. 744 745 @see wxGetFullHostName() 746 747 @header{wx/utils.h} 748 */ 749 wxString wxGetHostName(); 750 751 /** 752 @deprecated Use wxGetHostName() instead. 753 754 @param buf Buffer to store the host name in. 755 @param sz Size of the buffer. 756 757 @return @true if successful, @false otherwise. 758 759 @header{wx/utils.h} 760 */ 761 bool wxGetHostName(char* buf, int sz); 762 763 /** 764 Returns the FQDN (fully qualified domain host name) or an empty string on 765 error. 766 767 @see wxGetHostName() 768 769 @header{wx/utils.h} 770 */ 771 wxString wxGetFullHostName(); 772 773 /** 774 Returns the home directory for the given user. If the @a user is empty 775 (default value), this function behaves like wxGetHomeDir() (i.e. returns 776 the current user home directory). 777 778 If the home directory couldn't be determined, an empty string is returned. 779 780 @header{wx/utils.h} 781 */ 782 wxString wxGetUserHome(const wxString& user = wxEmptyString); 783 784 /** 785 This function returns the "user id" also known as "login name" under Unix 786 (i.e. something like "jsmith"). It uniquely identifies the current user (on 787 this system). Under Windows or NT, this function first looks in the 788 environment variables USER and LOGNAME; if neither of these is found, the 789 entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried. 790 791 @return The login name if successful or an empty string otherwise. 792 793 @see wxGetUserName() 794 795 @header{wx/utils.h} 796 */ 797 wxString wxGetUserId(); 798 799 /** 800 @deprecated Use wxGetUserId() instead. 801 802 @param buf Buffer to store the login name in. 803 @param sz Size of the buffer. 804 805 @return @true if successful, @false otherwise. 806 807 @header{wx/utils.h} 808 */ 809 bool wxGetUserId(char* buf, int sz); 810 811 /** 812 This function returns the full user name (something like "Mr. John Smith"). 813 814 Under Windows or NT, this function looks for the entry UserName in the 815 wxWidgets section of the WIN.INI file. If PenWindows is running, the entry 816 Current in the section User of the PENWIN.INI file is used. 817 818 @return The full user name if successful or an empty string otherwise. 819 820 @see wxGetUserId() 821 822 @header{wx/utils.h} 823 */ 824 wxString wxGetUserName(); 825 826 /** 827 @deprecated Use wxGetUserName() instead. 828 829 @param buf Buffer to store the full user name in. 830 @param sz Size of the buffer. 831 832 @return @true if successful, @false otherwise. 833 834 @header{wx/utils.h} 835 */ 836 bool wxGetUserName(char* buf, int sz); 837 838 /** 839 Returns the string containing the description of the current platform in a 840 user-readable form. For example, this function may return strings like 841 "Windows NT Version 4.0" or "Linux 2.2.2 i386". 842 843 @see wxGetOsVersion() 844 845 @header{wx/utils.h} 846 */ 847 wxString wxGetOsDescription(); 848 849 /** 850 Gets the version and the operating system ID for currently running OS. 851 The returned wxOperatingSystemId value can be used for a basic categorization 852 of the OS family; the major and minor version numbers allows detecting a specific 853 system. 854 855 For Unix-like systems (@c wxOS_UNIX) the major and minor version integers will 856 contain the kernel major and minor version numbers (as returned by the 857 'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19. 858 859 For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the 860 natural version numbers associated with the OS; e.g. "10" and "6" if the machine 861 is using Mac OS X Snow Leopard. 862 863 For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will 864 contain the following values: 865 @beginTable 866 @row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>} 867 @row3col{Windows 7, 6, 1} 868 @row3col{Windows Server 2008 R2, 6, 1} 869 @row3col{Windows Server 2008, 6, 0} 870 @row3col{Windows Vista, 6, 0} 871 @row3col{Windows Server 2003 R2, 5, 2} 872 @row3col{Windows Server 2003, 5, 2} 873 @row3col{Windows XP, 5, 1} 874 @row3col{Windows 2000, 5, 0} 875 @endDefList 876 See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a> 877 for more info about the values above. 878 879 @see wxGetOsDescription(), wxPlatformInfo 880 881 @header{wx/utils.h} 882 */ 883 wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL); 884 885 /** 886 Returns @true if the operating system the program is running under is 64 887 bit. The check is performed at run-time and may differ from the value 888 available at compile-time (at compile-time you can just check if 889 <tt>sizeof(void*) == 8</tt>) since the program could be running in 890 emulation mode or in a mixed 32/64 bit system (bi-architecture operating 891 system). 892 893 @note This function is not 100% reliable on some systems given the fact 894 that there isn't always a standard way to do a reliable check on the 895 OS architecture. 896 897 @header{wx/utils.h} 898 */ 899 bool wxIsPlatform64Bit(); 900 901 /** 902 Returns @true if the current platform is little endian (instead of big 903 endian). The check is performed at run-time. 904 905 @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros" 906 907 @header{wx/utils.h} 908 */ 909 bool wxIsPlatformLittleEndian(); 910 911 /** 912 Returns a structure containing information about the currently running 913 Linux distribution. 914 915 This function uses the @c lsb_release utility which is part of the 916 <tt>Linux Standard Base Core</tt> specification 917 (see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB 918 release 1.0 (released in 2001). 919 The @c lsb_release utility is very common on modern Linux distributions but in 920 case it's not available, then this function will return a ::wxLinuxDistributionInfo 921 structure containing empty strings. 922 923 This function is Linux-specific and is only available when the @c __LINUX__ 924 symbol is defined. 925 */ 926 wxLinuxDistributionInfo wxGetLinuxDistributionInfo(); 927 928 //@} 929 930 931 932 /** @addtogroup group_funcmacro_procctrl */ 933 //@{ 934 935 /** 936 @struct wxExecuteEnv 937 938 This structure can optionally be passed to wxExecute() to specify 939 additional options to use for the child process. 940 941 @since 2.9.2 942 943 @header{wx/utils.h} 944 */ 945 struct wxExecuteEnv 946 { 947 /** 948 The initial working directory for the new process. 949 950 If this field is empty, the current working directory of this process 951 is used. 952 */ 953 wxString cwd; 954 955 /** 956 The environment variable map. 957 958 If the map is empty, the environment variables of the current process 959 are also used for the child one, otherwise only the variables defined 960 in this map are used. 961 */ 962 wxEnvVariableHashMap env; 963 }; 964 965 /** 966 Bit flags that can be used with wxExecute(). 967 */ 968 enum 969 { 970 /** 971 Execute the process asynchronously. 972 973 Notice that, due to its value, this is the default. 974 */ 975 wxEXEC_ASYNC = 0, 976 977 /** 978 Execute the process synchronously. 979 */ 980 wxEXEC_SYNC = 1, 981 982 /** 983 Always show the child process console under MSW. 984 985 The child console is hidden by default if the child IO is redirected, 986 this flag allows changing this and showing it nevertheless. 987 988 This flag is ignored under the other platforms. 989 */ 990 wxEXEC_SHOW_CONSOLE = 2, 991 992 /** 993 Make the new process a group leader. 994 995 Under Unix, if the process is the group leader then passing 996 wxKILL_CHILDREN to wxKill() kills all children as well as pid. 997 998 Under MSW, applies only to console applications and is only supported 999 under NT family (i.e. not under Windows 9x). It corresponds to the 1000 native @c CREATE_NEW_PROCESS_GROUP and, in particular, ensures that 1001 Ctrl-Break signals will be sent to all children of this process as well 1002 to the process itself. Support for this flag under MSW was added in 1003 version 2.9.4 of wxWidgets. 1004 */ 1005 wxEXEC_MAKE_GROUP_LEADER = 4, 1006 1007 /** 1008 Don't disable the program UI while running the child synchronously. 1009 1010 By default synchronous execution disables all program windows to avoid 1011 that the user interacts with the program while the child process is 1012 running, you can use this flag to prevent this from happening. 1013 1014 This flag can only be used with ::wxEXEC_SYNC. 1015 */ 1016 wxEXEC_NODISABLE = 8, 1017 1018 /** 1019 Don't dispatch events while the child process is executed. 1020 1021 By default, the event loop is run while waiting for synchronous 1022 execution to complete and this flag can be used to simply block the 1023 main process until the child process finishes 1024 1025 This flag can only be used with ::wxEXEC_SYNC. 1026 */ 1027 wxEXEC_NOEVENTS = 16, 1028 1029 /** 1030 Hide child process console under MSW. 1031 1032 Under MSW, hide the console of the child process if it has one, 1033 even if its IO is not redirected. 1034 1035 This flag is ignored under the other platforms. 1036 */ 1037 wxEXEC_HIDE_CONSOLE = 32, 1038 1039 /** 1040 Convenient synonym for flags given system()-like behaviour. 1041 */ 1042 wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS 1043 }; 1044 /** 1045 Executes another program in Unix or Windows. 1046 1047 In the overloaded versions of this function, if @a flags parameter contains 1048 @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If 1049 it contains @c wxEXEC_SYNC, the current application waits until the other 1050 program has terminated. 1051 1052 In the case of synchronous execution, the return value is the exit code of 1053 the process (which terminates by the moment the function returns) and will 1054 be -1 if the process couldn't be started and typically 0 if the process 1055 terminated successfully. Also, while waiting for the process to terminate, 1056 wxExecute() will call wxYield(). Because of this, by default this function 1057 disables all application windows to avoid unexpected reentrancies which 1058 could result from the users interaction with the program while the child 1059 process is running. If you are sure that it is safe to not disable the 1060 program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this 1061 automatic disabling from happening. 1062 1063 For asynchronous execution, however, the return value is the process id and 1064 zero value indicates that the command could not be executed. As an added 1065 complication, the return value of -1 in this case indicates that we didn't 1066 launch a new process, but connected to the running one (this can only 1067 happen when using DDE under Windows for command execution). In particular, 1068 in this case only, the calling code will not get the notification about 1069 process termination. 1070 1071 If @a callback isn't @NULL and if execution is asynchronous, 1072 wxProcess::OnTerminate() will be called when the process finishes. 1073 Specifying this parameter also allows you to redirect the standard input 1074 and/or output of the process being launched by calling 1075 wxProcess::Redirect(). 1076 1077 Under Windows, when launching a console process its console is shown by 1078 default but hidden if its IO is redirected. Both of these default 1079 behaviours may be overridden: if ::wxEXEC_HIDE_CONSOLE is specified, the 1080 console will never be shown. If ::wxEXEC_SHOW_CONSOLE is used, the console 1081 will be shown even if the child process IO is redirected. Neither of these 1082 flags affect non-console Windows applications or does anything under the 1083 other systems. 1084 1085 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that 1086 the new process is a group leader (this will create a new session if 1087 needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as 1088 well as all of its children (except those which have started their own 1089 session). Under MSW, this flag can be used with console processes only and 1090 corresponds to the native @c CREATE_NEW_PROCESS_GROUP flag. 1091 1092 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking 1093 place while the child process is running. It should be only used for very 1094 short-lived processes as otherwise the application windows risk becoming 1095 unresponsive from the users point of view. As this flag only makes sense 1096 with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these 1097 flags is provided as a convenience. 1098 1099 @note Currently wxExecute() can only be used from the main thread, calling 1100 this function from another thread will result in an assert failure in 1101 debug build and won't work. 1102 1103 @param command 1104 The command to execute and any parameters to pass to it as a single 1105 string, i.e. "emacs file.txt". 1106 @param flags 1107 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include 1108 wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, wxEXEC_MAKE_GROUP_LEADER (in 1109 either case) or wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, 1110 which is equal to their combination, in wxEXEC_SYNC case. 1111 @param callback 1112 An optional pointer to wxProcess. 1113 @param env 1114 An optional pointer to additional parameters for the child process, 1115 such as its initial working directory and environment variables. This 1116 parameter is available in wxWidgets 2.9.2 and later only. 1117 1118 @see wxShell(), wxProcess, @ref page_samples_exec, 1119 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser() 1120 1121 @header{wx/utils.h} 1122 1123 @beginWxPerlOnly 1124 In wxPerl this function is called @c Wx::ExecuteCommand. 1125 @endWxPerlOnly 1126 */ 1127 long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, 1128 wxProcess* callback = NULL, 1129 const wxExecuteEnv* env = NULL); 1130 //@} 1131 1132 /** @addtogroup group_funcmacro_procctrl */ 1133 //@{ 1134 /** 1135 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), 1136 please see its documentation for general information. 1137 1138 This version takes an array of values: a command, any number of arguments, 1139 terminated by @NULL. 1140 1141 @param argv 1142 The command to execute should be the first element of this array, any 1143 additional ones are the command parameters and the array must be 1144 terminated with a @NULL pointer. 1145 @param flags 1146 Same as for wxExecute(const wxString&,int,wxProcess*) overload. 1147 @param callback 1148 An optional pointer to wxProcess. 1149 @param env 1150 An optional pointer to additional parameters for the child process, 1151 such as its initial working directory and environment variables. This 1152 parameter is available in wxWidgets 2.9.2 and later only. 1153 1154 @see wxShell(), wxProcess, @ref page_samples_exec, 1155 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser() 1156 1157 @header{wx/utils.h} 1158 1159 @beginWxPerlOnly 1160 In wxPerl this function is called @c Wx::ExecuteArgs. 1161 @endWxPerlOnly 1162 */ 1163 long wxExecute(char** argv, int flags = wxEXEC_ASYNC, 1164 wxProcess* callback = NULL, 1165 const wxExecuteEnv *env = NULL); 1166 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC, 1167 wxProcess* callback = NULL, 1168 const wxExecuteEnv *env = NULL); 1169 //@} 1170 1171 /** @addtogroup group_funcmacro_procctrl */ 1172 //@{ 1173 1174 /** 1175 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), 1176 please see its documentation for general information. 1177 1178 This version can be used to execute a process (always synchronously, the 1179 contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in 1180 the array @e output. 1181 1182 @param command 1183 The command to execute and any parameters to pass to it as a single 1184 string. 1185 @param output 1186 The string array where the stdout of the executed process is saved. 1187 @param flags 1188 Combination of flags to which ::wxEXEC_SYNC is always implicitly added. 1189 @param env 1190 An optional pointer to additional parameters for the child process, 1191 such as its initial working directory and environment variables. This 1192 parameter is available in wxWidgets 2.9.2 and later only. 1193 1194 @see wxShell(), wxProcess, @ref page_samples_exec, 1195 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser() 1196 1197 @header{wx/utils.h} 1198 1199 @beginWxPerlOnly 1200 This function is called @c Wx::ExecuteStdout: it only takes the 1201 @a command argument, and returns a 2-element list (@c status, @c output), 1202 where @c output in an array reference. 1203 @endWxPerlOnly 1204 */ 1205 long wxExecute(const wxString& command, wxArrayString& output, int flags = 0, 1206 const wxExecuteEnv *env = NULL); 1207 1208 /** 1209 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), 1210 please see its documentation for general information. 1211 1212 This version adds the possibility to additionally capture the messages from 1213 standard error output in the @a errors array. As with the above overload 1214 capturing standard output only, execution is always synchronous. 1215 1216 @param command 1217 The command to execute and any parameters to pass to it as a single 1218 string. 1219 @param output 1220 The string array where the stdout of the executed process is saved. 1221 @param errors 1222 The string array where the stderr of the executed process is saved. 1223 @param flags 1224 Combination of flags to which ::wxEXEC_SYNC is always implicitly added. 1225 @param env 1226 An optional pointer to additional parameters for the child process, 1227 such as its initial working directory and environment variables. This 1228 parameter is available in wxWidgets 2.9.2 and later only. 1229 1230 @see wxShell(), wxProcess, @ref page_samples_exec, 1231 wxLaunchDefaultApplication(), wxLaunchDefaultBrowser() 1232 1233 @header{wx/utils.h} 1234 1235 @beginWxPerlOnly 1236 This function is called @c Wx::ExecuteStdoutStderr: it only takes the 1237 @a command argument, and returns a 3-element list (@c status, @c output, 1238 @c errors), where @c output and @c errors are array references. 1239 @endWxPerlOnly 1240 */ 1241 long wxExecute(const wxString& command, wxArrayString& output, 1242 wxArrayString& errors, int flags = 0, 1243 const wxExecuteEnv *env = NULL); 1244 1245 /** 1246 Returns the number uniquely identifying the current process in the system. 1247 If an error occurs, 0 is returned. 1248 1249 @header{wx/utils.h} 1250 */ 1251 unsigned long wxGetProcessId(); 1252 1253 /** 1254 Equivalent to the Unix kill function: send the given signal @a sig to the 1255 process with PID @a pid. 1256 1257 The valid signal values are: 1258 1259 @code 1260 enum wxSignal 1261 { 1262 wxSIGNONE = 0, // verify if the process exists under Unix 1263 wxSIGHUP, 1264 wxSIGINT, 1265 wxSIGQUIT, 1266 wxSIGILL, 1267 wxSIGTRAP, 1268 wxSIGABRT, 1269 wxSIGEMT, 1270 wxSIGFPE, 1271 wxSIGKILL, // forcefully kill, dangerous! 1272 wxSIGBUS, 1273 wxSIGSEGV, 1274 wxSIGSYS, 1275 wxSIGPIPE, 1276 wxSIGALRM, 1277 wxSIGTERM // terminate the process gently 1278 }; 1279 @endcode 1280 1281 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under 1282 both Unix and Windows but all the other signals are equivalent to 1283 @c wxSIGTERM under Windows. Moreover, under Windows, @c wxSIGTERM is 1284 implemented by posting a message to the application window, so it only 1285 works if the application does have windows. If it doesn't, as is notably 1286 always the case for the console applications, you need to use @c wxSIGKILL 1287 to actually kill the process. Of course, this doesn't allow the process to 1288 shut down gracefully and so should be avoided if possible. 1289 1290 Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL, 1291 it will be filled with a value from the @c wxKillError enum: 1292 1293 @code 1294 enum wxKillError 1295 { 1296 wxKILL_OK, // no error 1297 wxKILL_BAD_SIGNAL, // no such signal 1298 wxKILL_ACCESS_DENIED, // permission denied 1299 wxKILL_NO_PROCESS, // no such process 1300 wxKILL_ERROR // another, unspecified error 1301 }; 1302 @endcode 1303 1304 The @a flags parameter can be wxKILL_NOCHILDREN (the default), or 1305 wxKILL_CHILDREN, in which case the child processes of this process will be 1306 killed too. Note that under Unix, for wxKILL_CHILDREN to work you should 1307 have created the process by passing wxEXEC_MAKE_GROUP_LEADER to 1308 wxExecute(). 1309 1310 @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec 1311 1312 @header{wx/utils.h} 1313 */ 1314 int wxKill(long pid, wxSignal sig = wxSIGTERM, 1315 wxKillError* rc = NULL, int flags = wxKILL_NOCHILDREN); 1316 1317 /** 1318 Executes a command in an interactive shell window. If no command is 1319 specified, then just the shell is spawned. 1320 1321 @see wxExecute(), @ref page_samples_exec 1322 1323 @header{wx/utils.h} 1324 */ 1325 bool wxShell(const wxString& command = wxEmptyString); 1326 1327 /** 1328 This function shuts down or reboots the computer depending on the value of 1329 the @a flags. 1330 1331 @note Note that performing the shutdown requires the corresponding access 1332 rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT) 1333 and that this function is only implemented under Unix and MSW. 1334 1335 @param flags 1336 One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or 1337 @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly 1338 combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by 1339 forcefully terminating all the applications. As doing this can result 1340 in a data loss, this flag shouldn't be used unless really necessary. 1341 1342 @return @true on success, @false if an error occurred. 1343 1344 @header{wx/utils.h} 1345 */ 1346 bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF); 1347 1348 //@} 1349 1350 1351 1352 /** @addtogroup group_funcmacro_time */ 1353 //@{ 1354 1355 /** 1356 Sleeps for the specified number of microseconds. The microsecond resolution 1357 may not, in fact, be available on all platforms (currently only Unix 1358 platforms with nanosleep(2) may provide it) in which case this is the same 1359 as calling wxMilliSleep() with the argument of @e microseconds/1000. 1360 1361 @header{wx/utils.h} 1362 */ 1363 void wxMicroSleep(unsigned long microseconds); 1364 1365 /** 1366 Sleeps for the specified number of milliseconds. Notice that usage of this 1367 function is encouraged instead of calling usleep(3) directly because the 1368 standard @e usleep() function is not MT safe. 1369 1370 @header{wx/utils.h} 1371 */ 1372 void wxMilliSleep(unsigned long milliseconds); 1373 1374 /** 1375 Returns a string representing the current date and time. 1376 1377 @header{wx/utils.h} 1378 */ 1379 wxString wxNow(); 1380 1381 /** 1382 Sleeps for the specified number of seconds. 1383 1384 @header{wx/utils.h} 1385 */ 1386 void wxSleep(int secs); 1387 1388 /** 1389 @deprecated This function is deprecated because its name is misleading: 1390 notice that the argument is in milliseconds, not microseconds. 1391 Please use either wxMilliSleep() or wxMicroSleep() depending on 1392 the resolution you need. 1393 1394 Sleeps for the specified number of milliseconds. 1395 1396 @header{wx/utils.h} 1397 */ 1398 void wxUsleep(unsigned long milliseconds); 1399 1400 //@} 1401 1402