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