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