interface/wx/utils.h

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