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 /** @addtogroup 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 /** @addtogroup 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 /** @addtogroup 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     @see wxLaunchDefaultBrowser(), wxExecute()
 353
 354     @header{wx/utils.h}
 355 */
 356 bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
 357
 358 /**
 359     Opens the @a url in user's default browser.
 360
 361     If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
 362     window is opened for the URL (currently this is only supported under
 363     Windows).
 364
 365     And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
 366     a busy cursor is shown while the browser is being launched (using
 367     wxBusyCursor).
 368
 369     The @a url may also be a local file path (with or without the "file://"
 370     prefix), if it doesn't correspond to an existing file and the URL has no
 371     scheme "http://" is prepended to it by default.
 372
 373     Returns @true if the application was successfully launched.
 374
 375     @note For some configurations of the running user, the application which is
 376           launched to open the given URL may be URL-dependent (e.g. a browser
 377           may be used for local URLs while another one may be used for remote
 378           URLs).
 379
 380     @see wxLaunchDefaultApplication(), wxExecute()
 381
 382     @header{wx/utils.h}
 383 */
 384 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 385
 386 /**
 387     Loads a user-defined Windows resource as a string. If the resource is
 388     found, the function creates a new character array and copies the data into
 389     it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
 390
 391     The resource must be defined in the @c .rc file using the following syntax:
 392
 393     @code
 394     myResource TEXT file.ext
 395     @endcode
 396
 397     Where @c file.ext is a file that the resource compiler can find.
 398
 399     This function is available under Windows only.
 400
 401     @header{wx/utils.h}
 402 */
 403 wxString wxLoadUserResource(const wxString& resourceName,
 404                             const wxString& resourceType = "TEXT");
 405
 406 /**
 407     @deprecated Replaced by wxWindow::Close(). See the
 408                 @ref overview_windowdeletion "window deletion overview".
 409
 410     Tells the system to delete the specified object when all other events have
 411     been processed. In some environments, it is necessary to use this instead
 412     of deleting a frame directly with the delete operator, because some GUIs
 413     will still send events to a deleted window.
 414
 415     @header{wx/utils.h}
 416 */
 417 void wxPostDelete(wxObject* object);
 418
 419 /**
 420     Under X only, sets the current display name. This is the X host and display
 421     name such as "colonsay:0.0", and the function indicates which display
 422     should be used for creating windows from this point on. Setting the display
 423     within an application allows multiple displays to be used.
 424
 425     @see wxGetDisplayName()
 426
 427     @header{wx/utils.h}
 428 */
 429 void wxSetDisplayName(const wxString& displayName);
 430
 431 /**
 432     Strips any menu codes from @a str and returns the result.
 433
 434     By default, the functions strips both the mnemonics character (@c '&')
 435     which is used to indicate a keyboard shortkey, and the accelerators, which
 436     are used only in the menu items and are separated from the main text by the
 437     @c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
 438     @c wxStrip_Accel to strip only the former or the latter part, respectively.
 439
 440     Notice that in most cases wxMenuItem::GetLabelFromText() or
 441     wxControl::GetLabelText() can be used instead.
 442
 443     @header{wx/utils.h}
 444 */
 445 wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
 446
 447 //@}
 448
 449
 450
 451 /** @addtogroup group_funcmacro_networkuseros */
 452 //@{
 453
 454 /**
 455     Copies the user's email address into the supplied buffer, by concatenating
 456     the values returned by wxGetFullHostName() and wxGetUserId().
 457
 458     @return @true if successful, @false otherwise.
 459
 460     @header{wx/utils.h}
 461 */
 462 wxString wxGetEmailAddress();
 463
 464 /**
 465     @deprecated Use wxGetEmailAddress() instead.
 466
 467     @param buf Buffer to store the email address in.
 468     @param sz  Size of the buffer.
 469
 470     @return @true if successful, @false otherwise.
 471
 472     @header{wx/utils.h}
 473 */
 474 bool wxGetEmailAddress(char* buf, int sz);
 475
 476 /**
 477     Returns the amount of free memory in bytes under environments which support
 478     it, and -1 if not supported or failed to perform measurement.
 479
 480     @header{wx/utils.h}
 481 */
 482 wxMemorySize wxGetFreeMemory();
 483
 484 /**
 485     Return the (current) user's home directory.
 486
 487     @see wxGetUserHome(), wxStandardPaths
 488
 489     @header{wx/utils.h}
 490 */
 491 wxString wxGetHomeDir();
 492
 493 /**
 494     Copies the current host machine's name into the supplied buffer. Please
 495     note that the returned name is @e not fully qualified, i.e. it does not
 496     include the domain name.
 497
 498     Under Windows or NT, this function first looks in the environment variable
 499     SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
 500     section of the WIN.INI file is tried.
 501
 502     @return The hostname if successful or an empty string otherwise.
 503
 504     @see wxGetFullHostName()
 505
 506     @header{wx/utils.h}
 507 */
 508 wxString wxGetHostName();
 509
 510 /**
 511     @deprecated Use wxGetHostName() instead.
 512
 513     @param buf Buffer to store the host name in.
 514     @param sz  Size of the buffer.
 515
 516     @return @true if successful, @false otherwise.
 517
 518     @header{wx/utils.h}
 519 */
 520 bool wxGetHostName(char* buf, int sz);
 521
 522 /**
 523     Returns the FQDN (fully qualified domain host name) or an empty string on
 524     error.
 525
 526     @see wxGetHostName()
 527
 528     @header{wx/utils.h}
 529 */
 530 wxString wxGetFullHostName();
 531
 532 /**
 533     Returns the home directory for the given user. If the @a user is empty
 534     (default value), this function behaves like wxGetHomeDir() (i.e. returns
 535     the current user home directory).
 536
 537     If the home directory couldn't be determined, an empty string is returned.
 538
 539     @header{wx/utils.h}
 540 */
 541 wxString wxGetUserHome(const wxString& user = "");
 542
 543 /**
 544     This function returns the "user id" also known as "login name" under Unix
 545     (i.e. something like "jsmith"). It uniquely identifies the current user (on
 546     this system).  Under Windows or NT, this function first looks in the
 547     environment variables USER and LOGNAME; if neither of these is found, the
 548     entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
 549
 550     @return The login name if successful or an empty string otherwise.
 551
 552     @see wxGetUserName()
 553
 554     @header{wx/utils.h}
 555 */
 556 wxString wxGetUserId();
 557
 558 /**
 559     @deprecated Use wxGetUserId() instead.
 560
 561     @param buf Buffer to store the login name in.
 562     @param sz  Size of the buffer.
 563
 564     @return @true if successful, @false otherwise.
 565
 566     @header{wx/utils.h}
 567 */
 568 bool wxGetUserId(char* buf, int sz);
 569
 570 /**
 571     This function returns the full user name (something like "Mr. John Smith").
 572
 573     Under Windows or NT, this function looks for the entry UserName in the
 574     wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
 575     Current in the section User of the PENWIN.INI file is used.
 576
 577     @return The full user name if successful or an empty string otherwise.
 578
 579     @see wxGetUserId()
 580
 581     @header{wx/utils.h}
 582 */
 583 wxString wxGetUserName();
 584
 585 /**
 586     @deprecated Use wxGetUserName() instead.
 587
 588     @param buf Buffer to store the full user name in.
 589     @param sz  Size of the buffer.
 590
 591     @return @true if successful, @false otherwise.
 592
 593     @header{wx/utils.h}
 594 */
 595 bool wxGetUserName(char* buf, int sz);
 596
 597 /**
 598     Returns the string containing the description of the current platform in a
 599     user-readable form. For example, this function may return strings like
 600     "Windows NT Version 4.0" or "Linux 2.2.2 i386".
 601
 602     @see wxGetOsVersion()
 603
 604     @header{wx/utils.h}
 605 */
 606 wxString wxGetOsDescription();
 607
 608 /**
 609     Gets the version and the operating system ID for currently running OS. See
 610     wxPlatformInfo for more details about wxOperatingSystemId.
 611
 612     @see wxGetOsDescription(), wxPlatformInfo
 613
 614     @header{wx/utils.h}
 615 */
 616 wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);
 617
 618 /**
 619     Returns @true if the operating system the program is running under is 64
 620     bit. The check is performed at run-time and may differ from the value
 621     available at compile-time (at compile-time you can just check if
 622     <tt>sizeof(void*) == 8</tt>) since the program could be running in
 623     emulation mode or in a mixed 32/64 bit system (bi-architecture operating
 624     system).
 625
 626     @note This function is not 100% reliable on some systems given the fact
 627           that there isn't always a standard way to do a reliable check on the
 628           OS architecture.
 629
 630     @header{wx/utils.h}
 631 */
 632 bool wxIsPlatform64Bit();
 633
 634 /**
 635     Returns @true if the current platform is little endian (instead of big
 636     endian). The check is performed at run-time.
 637
 638     @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"
 639
 640     @header{wx/utils.h}
 641 */
 642 bool wxIsPlatformLittleEndian();
 643
 644 //@}
 645
 646
 647
 648 /** @addtogroup group_funcmacro_procctrl */
 649 //@{
 650
 651 /**
 652     Executes another program in Unix or Windows.
 653
 654     In the overloaded versions of this function, if @a flags parameter contains
 655     @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
 656     it contains @c wxEXEC_SYNC, the current application waits until the other
 657     program has terminated.
 658
 659     In the case of synchronous execution, the return value is the exit code of
 660     the process (which terminates by the moment the function returns) and will
 661     be -1 if the process couldn't be started and typically 0 if the process
 662     terminated successfully. Also, while waiting for the process to terminate,
 663     wxExecute() will call wxYield(). Because of this, by default this function
 664     disables all application windows to avoid unexpected reentrancies which
 665     could result from the users interaction with the program while the child
 666     process is running. If you are sure that it is safe to not disable the
 667     program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
 668     automatic disabling from happening.
 669
 670     For asynchronous execution, however, the return value is the process id and
 671     zero value indicates that the command could not be executed. As an added
 672     complication, the return value of -1 in this case indicates that we didn't
 673     launch a new process, but connected to the running one (this can only
 674     happen when using DDE under Windows for command execution). In particular,
 675     in this case only, the calling code will not get the notification about
 676     process termination.
 677
 678     If @a callback isn't @NULL and if execution is asynchronous,
 679     wxProcess::OnTerminate() will be called when the process finishes.
 680     Specifying this parameter also allows you to redirect the standard input
 681     and/or output of the process being launched by calling
 682     wxProcess::Redirect(). If the child process IO is redirected, under Windows
 683     the process window is not shown by default (this avoids having to flush an
 684     unnecessary console for the processes which don't create any windows
 685     anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
 686     happening, i.e. with this flag the child process window will be shown
 687     normally.
 688
 689     Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
 690     the new process is a group leader (this will create a new session if
 691     needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
 692     well as all of its children (except those which have started their own
 693     session).
 694
 695     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
 696     place while the child process is running. It should be only used for very
 697     short-lived processes as otherwise the application windows risk becoming
 698     unresponsive from the users point of view. As this flag only makes sense
 699     with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
 700     flags is provided as a convenience.
 701
 702     @note Currently wxExecute() can only be used from the main thread, calling
 703           this function from another thread will result in an assert failure in
 704           debug build and won't work.
 705
 706     @param command
 707         The command to execute and any parameters to pass to it as a single
 708         string, i.e. "emacs file.txt".
 709     @param flags
 710         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
 711         wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
 712         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
 713         their combination, in wxEXEC_SYNC case.
 714     @param callback
 715         An optional pointer to wxProcess.
 716
 717     @see wxShell(), wxProcess, @ref page_samples_exec,
 718          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 719
 720     @header{wx/utils.h}
 721
 722     @beginWxPerlOnly
 723     This function is called @c Wx::ExecuteStdoutStderr and it only takes the
 724     @a command argument, and returns a 3-element list (@c status, @c output,
 725     @c errors), where @c output and @c errors are array references.
 726     @endWxPerlOnly
 727 */
 728 long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
 729                 wxProcess* callback = NULL);
 730
 731 //@}
 732
 733 /** @addtogroup group_funcmacro_procctrl */
 734 //@{
 735 /**
 736     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
 737     please see its documentation for general information.
 738
 739     This version takes an array of values: a command, any number of arguments,
 740     terminated by @NULL.
 741
 742     @param argv
 743         The command to execute should be the first element of this array, any
 744         additional ones are the command parameters and the array must be
 745         terminated with a @NULL pointer.
 746     @param flags
 747         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
 748         wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
 749         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
 750         their combination, in wxEXEC_SYNC case.
 751     @param callback
 752         An optional pointer to wxProcess.
 753
 754     @see wxShell(), wxProcess, @ref page_samples_exec,
 755          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 756
 757     @header{wx/utils.h}
 758 */
 759 long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
 760                 wxProcess* callback = NULL);
 761 long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
 762                 wxProcess* callback = NULL);
 763 //@}
 764
 765 /** @addtogroup group_funcmacro_procctrl */
 766 //@{
 767
 768 /**
 769     This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
 770     please see its documentation for general information.
 771
 772     This version can be used to execute a process (always synchronously, the
 773     contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
 774     the array @e output.
 775
 776     @param command
 777         The command to execute and any parameters to pass to it as a single
 778         string.
 779     @param output
 780         The string array where the stdout of the executed process is saved.
 781     @param flags
 782         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
 783         wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
 784         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
 785         their combination, in wxEXEC_SYNC case.
 786
 787     @see wxShell(), wxProcess, @ref page_samples_exec,
 788          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 789
 790     @header{wx/utils.h}
 791 */
 792 long wxExecute(const wxString& command, wxArrayString& output, int flags = 0);
 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 adds the possibility to additionally capture the messages from
 799     standard error output in the @a errors array.
 800
 801     @param command
 802         The command to execute and any parameters to pass to it as a single
 803         string.
 804     @param output
 805         The string array where the stdout of the executed process is saved.
 806     @param errors
 807         The string array where the stderr of the executed process is saved.
 808     @param flags
 809         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
 810         wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
 811         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
 812         their combination, in wxEXEC_SYNC case.
 813
 814     @see wxShell(), wxProcess, @ref page_samples_exec,
 815          wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
 816
 817     @header{wx/utils.h}
 818 */
 819 long wxExecute(const wxString& command, wxArrayString& output,
 820                 wxArrayString& errors, int flags = 0);
 821
 822 /**
 823     Returns the number uniquely identifying the current process in the system.
 824     If an error occurs, 0 is returned.
 825
 826     @header{wx/utils.h}
 827 */
 828 unsigned long wxGetProcessId();
 829
 830 /**
 831     Equivalent to the Unix kill function: send the given signal @a sig to the
 832     process with PID @a pid. The valid signal values are:
 833
 834     @code
 835     enum wxSignal
 836     {
 837         wxSIGNONE = 0, // verify if the process exists under Unix
 838         wxSIGHUP,
 839         wxSIGINT,
 840         wxSIGQUIT,
 841         wxSIGILL,
 842         wxSIGTRAP,
 843         wxSIGABRT,
 844         wxSIGEMT,
 845         wxSIGFPE,
 846         wxSIGKILL,     // forcefully kill, dangerous!
 847         wxSIGBUS,
 848         wxSIGSEGV,
 849         wxSIGSYS,
 850         wxSIGPIPE,
 851         wxSIGALRM,
 852         wxSIGTERM      // terminate the process gently
 853     };
 854     @endcode
 855
 856     @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
 857     both Unix and Windows but all the other signals are equivalent to
 858     @c wxSIGTERM under Windows.
 859
 860     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
 861     it will be filled with a value of the the @c wxKillError enum:
 862
 863     @code
 864     enum wxKillError
 865     {
 866         wxKILL_OK,            // no error
 867         wxKILL_BAD_SIGNAL,    // no such signal
 868         wxKILL_ACCESS_DENIED, // permission denied
 869         wxKILL_NO_PROCESS,    // no such process
 870         wxKILL_ERROR          // another, unspecified error
 871     };
 872     @endcode
 873
 874     The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
 875     wxKILL_CHILDREN, in which case the child processes of this process will be
 876     killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
 877     have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
 878     wxExecute().
 879
 880     @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec
 881
 882     @header{wx/utils.h}
 883 */
 884 int wxKill(long pid, int sig = wxSIGTERM,
 885             wxKillError rc = NULL, int flags = 0);
 886
 887 /**
 888     Executes a command in an interactive shell window. If no command is
 889     specified, then just the shell is spawned.
 890
 891     @see wxExecute(), @ref page_samples_exec
 892
 893     @header{wx/utils.h}
 894 */
 895 bool wxShell(const wxString& command = NULL);
 896
 897 /**
 898     This function shuts down or reboots the computer depending on the value of
 899     the @a flags.
 900
 901     @note Note that performing the shutdown requires the corresponding access
 902         rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT)
 903         and that this function is only implemented under Unix and MSW.
 904
 905     @param flags
 906         One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
 907         @c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
 908         combined with @c wxSHUTDOWN_FORCE which forces shutdown under MSW by
 909         forcefully terminating all the applications. As doing this can result
 910         in a data loss, this flag shouldn't be used unless really necessary.
 911
 912     @return @true on success, @false if an error occurred.
 913
 914     @header{wx/utils.h}
 915 */
 916 bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
 917
 918 //@}
 919
 920
 921
 922 /** @addtogroup group_funcmacro_time */
 923 //@{
 924
 925 /**
 926     Sleeps for the specified number of microseconds. The microsecond resolution
 927     may not, in fact, be available on all platforms (currently only Unix
 928     platforms with nanosleep(2) may provide it) in which case this is the same
 929     as calling wxMilliSleep() with the argument of @e microseconds/1000.
 930
 931     @header{wx/utils.h}
 932 */
 933 void wxMicroSleep(unsigned long microseconds);
 934
 935 /**
 936     Sleeps for the specified number of milliseconds. Notice that usage of this
 937     function is encouraged instead of calling usleep(3) directly because the
 938     standard @e usleep() function is not MT safe.
 939
 940     @header{wx/utils.h}
 941 */
 942 void wxMilliSleep(unsigned long milliseconds);
 943
 944 /**
 945     Returns a string representing the current date and time.
 946
 947     @header{wx/utils.h}
 948 */
 949 wxString wxNow();
 950
 951 /**
 952     Sleeps for the specified number of seconds.
 953
 954     @header{wx/utils.h}
 955 */
 956 void wxSleep(int secs);
 957
 958 /**
 959     @deprecated This function is deprecated because its name is misleading:
 960                 notice that the argument is in milliseconds, not microseconds.
 961                 Please use either wxMilliSleep() or wxMicroSleep() depending on
 962                 the resolution you need.
 963
 964     Sleeps for the specified number of milliseconds.
 965
 966     @header{wx/utils.h}
 967 */
 968 void wxUsleep(unsigned long milliseconds);
 969
 970 //@}
 971