interface/utils.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        utils.h
   3 // Purpose:     interface of wxWindowDisabler
   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 exception
  14     of one of them) in its constructor and enables them back in its destructor.
  15     This comes in handy when you want to indicate to the user that the application
  16     is currently busy and cannot respond to user input.
  17
  18     @library{wxcore}
  19     @category{FIXME}
  20
  21     @see wxBusyCursor
  22 */
  23 class wxWindowDisabler
  24 {
  25 public:
  26     /**
  27         Disables all top level windows of the applications with the exception of
  28         @a winToSkip if it is not @NULL.
  29     */
  30     wxWindowDisabler(wxWindow* winToSkip = NULL);
  31
  32     /**
  33         Reenables back the windows disabled by the constructor.
  34     */
  35     ~wxWindowDisabler();
  36 };
  37
  38
  39
  40 /**
  41     @class wxBusyCursor
  42     @wxheader{utils.h}
  43
  44     This class makes it easy to tell your user that the program is temporarily busy.
  45     Just create a wxBusyCursor object on the stack, and within the current scope,
  46     the hourglass will be shown.
  47
  48     For example:
  49
  50     @code
  51     wxBusyCursor wait;
  52
  53       for (int i = 0; i  100000; i++)
  54         DoACalculation();
  55     @endcode
  56
  57     It works by calling wxBeginBusyCursor() in the constructor,
  58     and wxEndBusyCursor() in the destructor.
  59
  60     @library{wxcore}
  61     @category{FIXME}
  62
  63     @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
  64 */
  65 class wxBusyCursor
  66 {
  67 public:
  68     /**
  69         Constructs a busy cursor object, calling wxBeginBusyCursor().
  70     */
  71     wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
  72
  73     /**
  74         Destroys the busy cursor object, calling wxEndBusyCursor().
  75     */
  76     ~wxBusyCursor();
  77 };
  78
  79
  80
  81 // ============================================================================
  82 // Global functions/macros
  83 // ============================================================================
  84
  85
  86 /** @ingroup group_funcmacro_dialog */
  87 //@{
  88
  89 /**
  90     Changes the cursor to the given cursor for all windows in the application.
  91     Use wxEndBusyCursor() to revert the cursor back to its previous state.
  92     These two calls can be nested, and a counter ensures that only the outer
  93     calls take effect.
  94
  95     @see wxIsBusy(), wxBusyCursor
  96
  97     @header{wx/utils.h}
  98 */
  99 void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
 100
 101 /**
 102     Changes the cursor back to the original cursor, for all windows in the
 103     application. Use with wxBeginBusyCursor().
 104
 105     @see wxIsBusy(), wxBusyCursor
 106
 107     @header{wx/utils.h}
 108 */
 109 void wxEndBusyCursor();
 110
 111 /**
 112     Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
 113     calls.
 114
 115     @see wxBusyCursor.
 116
 117     @header{wx/utils.h}
 118 */
 119 bool wxIsBusy();
 120
 121 /**
 122     Ring the system bell.
 123
 124     @note This function is categorized as a GUI one and so is not thread-safe.
 125
 126     @header{wx/utils.h}
 127 */
 128 void wxBell();
 129
 130 /**
 131     Shows a message box with the information about the wxWidgets build used,
 132     including its version, most important build parameters and the version of
 133     the underlying GUI toolkit. This is mainly used for diagnostic purposes
 134     and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
 135     doesn't otherwise handle this event.
 136
 137     @wxsince{2.9.0}
 138
 139     @header{wx/utils.h}
 140 */
 141 void wxInfoMessageBox(wxWindow parent = NULL);
 142
 143 //@}
 144
 145
 146
 147 /** @ingroup group_funcmacro_env */
 148 //@{
 149
 150 /**
 151     This is a macro defined as @c getenv() or its wide char version in Unicode
 152     mode.
 153
 154     Note that under Win32 it may not return correct value for the variables set
 155     with wxSetEnv(), use wxGetEnv() function instead.
 156
 157     @header{wx/utils.h}
 158 */
 159 wxChar* wxGetenv(const wxString& var);
 160
 161 /**
 162     Returns the current value of the environment variable @c var in @c value.
 163     @c value may be @NULL if you just want to know if the variable exists and
 164     are not interested in its value.
 165
 166     Returns @true if the variable exists, @false otherwise.
 167
 168     @header{wx/utils.h}
 169 */
 170 bool wxGetEnv(const wxString& var, wxString* value);
 171
 172 /**
 173     Sets the value of the environment variable @c var (adding it if necessary)
 174     to @c value.
 175
 176     Returns @true on success.
 177
 178     @see wxUnsetEnv()
 179
 180     @header{wx/utils.h}
 181 */
 182 bool wxSetEnv(const wxString& var, const wxString& value);
 183
 184 /**
 185     Removes the variable @c var from the environment. wxGetEnv() will return
 186     @NULL after the call to this function.
 187
 188     Returns @true on success.
 189
 190     @header{wx/utils.h}
 191 */
 192 bool wxUnsetEnv(const wxString& var);
 193
 194 //@}
 195
 196
 197
 198 /**
 199     Returns the type of power source as one of @c wxPOWER_SOCKET,
 200     @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
 201     @c wxPOWER_UNKNOWN is also the default on platforms where this
 202     feature is not implemented (currently everywhere but MS Windows).
 203
 204     @header{wx/utils.h}
 205 */
 206 wxPowerType wxGetPowerType();
 207
 208 //@{
 209 /**
 210     This function returns the "user id" also known as "login name" under Unix i.e.
 211     something like "jsmith". It uniquely identifies the current user (on this
 212     system).
 213     Under Windows or NT, this function first looks in the environment
 214     variables USER and LOGNAME; if neither of these is found, the entry @b UserId
 215     in the @b wxWidgets section of the WIN.INI file is tried.
 216     The first variant of this function returns the login name if successful or an
 217     empty string otherwise. The second (deprecated) function returns @true
 218     if successful, @false otherwise.
 219
 220     @see wxGetUserName()
 221
 222     @header{wx/utils.h}
 223 */
 224 wxString wxGetUserId();
 225 bool wxGetUserId(char* buf, int sz);
 226 //@}
 227
 228 /**
 229     @b NB: This function is now obsolete, please use
 230     wxLogFatalError() instead.
 231     Displays @a msg and exits. This writes to standard error under Unix,
 232     and pops up a message box under Windows. Used for fatal internal
 233     wxWidgets errors. See also wxError().
 234
 235     @header{wx/utils.h}
 236 */
 237 void wxFatalError(const wxString& msg,
 238                   const wxString& title = "wxWidgets Fatal Error");
 239
 240 /**
 241     Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
 242     @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
 243     @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
 244     @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where
 245     this feature is not implemented (currently everywhere but MS Windows).
 246
 247     @header{wx/utils.h}
 248 */
 249 wxBatteryState wxGetBatteryState();
 250
 251 /**
 252     @b NB: This function is obsolete, please use
 253     wxWindow::FindWindowByName instead.
 254     Find a window by its name (as given in a window constructor or @b Create
 255     function call).
 256     If @a parent is @NULL, the search will start from all top-level
 257     frames and dialog boxes; if non-@NULL, the search will be limited to the given
 258     window hierarchy.
 259     The search is recursive in both cases.
 260     If no such named window is found, @b wxFindWindowByLabel is called.
 261
 262     @header{wx/utils.h}
 263 */
 264 wxWindow* wxFindWindowByName(const wxString& name,
 265                              wxWindow* parent = NULL);
 266
 267 /**
 268     This function is deprecated as the ids generated by it can conflict with the
 269     ids defined by the user code, use @c wxID_ANY to assign ids which are
 270     guaranteed to not conflict with the user-defined ids for the controls and menu
 271     items you create instead of using this function.
 272
 273     Generates an integer identifier unique to this run of the program.
 274
 275     @header{wx/utils.h}
 276 */
 277 long wxNewId();
 278
 279 /**
 280     Ensures that ids subsequently generated by @b NewId do not clash with
 281     the given @b id.
 282
 283     @header{wx/utils.h}
 284 */
 285 void wxRegisterId(long id);
 286
 287 /**
 288     @b NB: This function is now obsolete, replaced by Log
 289     functions() and wxLogDebug() in particular.
 290     Display a debugging message; under Windows, this will appear on the
 291     debugger command window, and under Unix, it will be written to standard
 292     error.
 293     The syntax is identical to @b printf: pass a format string and a
 294     variable list of arguments.
 295     @b Tip: under Windows, if your application crashes before the
 296     message appears in the debugging window, put a wxYield call after
 297     each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
 298     (at least for Watcom C++): preformat your messages and use OutputDebugString
 299     instead.
 300
 301     @header{wx/utils.h}
 302 */
 303 void wxDebugMsg(const wxString& fmt, ... );
 304
 305 /**
 306     For normal keys, returns @true if the specified key is currently down.
 307     For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
 308     @true if the key is toggled such that its LED indicator is lit. There is
 309     currently no way to test whether togglable keys are up or down.
 310     Even though there are virtual key codes defined for mouse buttons, they
 311     cannot be used with this function currently.
 312
 313     @header{wx/utils.h}
 314 */
 315 bool wxGetKeyState(wxKeyCode key);
 316
 317 /**
 318     Returns the string containing the description of the current platform in a
 319     user-readable form. For example, this function may return strings like
 320     @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
 321
 322     @see ::wxGetOsVersion
 323
 324     @header{wx/utils.h}
 325 */
 326 wxString wxGetOsDescription();
 327
 328 /**
 329     Return the (current) user's home directory.
 330
 331     @see wxGetUserHome(), wxStandardPaths
 332
 333     @header{wx/utils.h}
 334 */
 335 wxString wxGetHomeDir();
 336
 337 /**
 338     Sleeps for the specified number of milliseconds. Notice that usage of this
 339     function is encouraged instead of calling usleep(3) directly because the
 340     standard usleep() function is not MT safe.
 341
 342     @header{wx/utils.h}
 343 */
 344 void wxMilliSleep(unsigned long milliseconds);
 345
 346 /**
 347     Sleeps for the specified number of microseconds. The microsecond resolution may
 348     not, in fact, be available on all platforms (currently only Unix platforms with
 349     nanosleep(2) may provide it) in which case this is the same as
 350     wxMilliSleep()(@e microseconds/1000).
 351
 352     @header{wx/utils.h}
 353 */
 354 void wxMicroSleep(unsigned long microseconds);
 355
 356
 357 /**
 358     Find a menu item identifier associated with the given frame's menu bar.
 359
 360     @header{wx/utils.h}
 361 */
 362 int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
 363                     const wxString& itemString);
 364
 365 /**
 366     This function enables or disables all top level windows. It is used by
 367     ::wxSafeYield.
 368
 369     @header{wx/utils.h}
 370 */
 371 void wxEnableTopLevelWindows(bool enable = true);
 372
 373 /**
 374     Strips any menu codes from @a str and returns the result.
 375     By default, the functions strips both the mnemonics character (@c '')
 376     which is used to indicate a keyboard shortkey, and the accelerators, which are
 377     used only in the menu items and are separated from the main text by the
 378     @c \t (TAB) character. By using @a flags of
 379     @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
 380     or the latter part, respectively.
 381     Notice that in most cases
 382     wxMenuItem::GetLabelFromText or
 383     wxControl::GetLabelText can be used instead.
 384
 385     @header{wx/utils.h}
 386 */
 387 wxString wxStripMenuCodes(const wxString& str,
 388                             int flags = wxStrip_All);
 389
 390 /**
 391     @b NB: This function is now obsolete, please use wxLogError()
 392     instead.
 393     Displays @a msg and continues. This writes to standard error under
 394     Unix, and pops up a message box under Windows. Used for internal
 395     wxWidgets errors. See also wxFatalError().
 396
 397     @header{wx/utils.h}
 398 */
 399 void wxError(const wxString& msg,
 400             const wxString& title = "wxWidgets Internal Error");
 401
 402 /**
 403     Open the @a url in user's default browser. If @a flags parameter contains
 404     @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
 405     (currently this is only supported under Windows). The @a url may also be a
 406     local file path (with or without @c file:// prefix), if it doesn't
 407     correspond to an existing file and the URL has no scheme @c http:// is
 408     prepended to it by default.
 409     Returns @true if the application was successfully launched.
 410     Note that for some configurations of the running user, the application which
 411     is launched to open the given URL may be URL-dependent (e.g. a browser may be
 412     used for
 413     local URLs while another one may be used for remote URLs).
 414
 415     @header{wx/utils.h}
 416 */
 417 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 418
 419 /**
 420     Executes a command in an interactive shell window. If no command is
 421     specified, then just the shell is spawned.
 422     See also wxExecute(), @ref overview_sampleexec "Exec sample".
 423
 424     @header{wx/utils.h}
 425 */
 426 bool wxShell(const wxString& command = NULL);
 427
 428 /**
 429     Gets the version and the operating system ID for currently running OS.
 430     See wxPlatformInfo for more details about wxOperatingSystemId.
 431
 432     @see ::wxGetOsDescription, wxPlatformInfo
 433
 434     @header{wx/utils.h}
 435 */
 436 wxOperatingSystemId wxGetOsVersion(int* major = NULL,
 437                                     int* minor = NULL);
 438
 439 /**
 440     Returns the FQDN (fully qualified domain host name) or an empty string on
 441     error.
 442
 443     @see wxGetHostName()
 444
 445     @header{wx/utils.h}
 446 */
 447 wxString wxGetFullHostName();
 448
 449 /**
 450     Tells the system to delete the specified object when
 451     all other events have been processed. In some environments, it is
 452     necessary to use this instead of deleting a frame directly with the
 453     delete operator, because some GUIs will still send events to a deleted window.
 454     Now obsolete: use wxWindow::Close instead.
 455
 456     @header{wx/utils.h}
 457 */
 458 void wxPostDelete(wxObject* object);
 459
 460 /**
 461     @b NB: This function is obsolete, please use
 462     wxWindow::FindWindowByLabel instead.
 463     Find a window by its label. Depending on the type of window, the label may be a
 464     window title
 465     or panel item label. If @a parent is @NULL, the search will start from all
 466     top-level
 467     frames and dialog boxes; if non-@NULL, the search will be limited to the given
 468     window hierarchy.
 469     The search is recursive in both cases.
 470
 471     @header{wx/utils.h}
 472 */
 473 wxWindow* wxFindWindowByLabel(const wxString& label,
 474                                 wxWindow* parent = NULL);
 475
 476
 477 /**
 478     Returns the mouse position in screen coordinates.
 479
 480     @header{wx/utils.h}
 481 */
 482 wxPoint wxGetMousePosition();
 483
 484 /**
 485     Loads a user-defined Windows resource as a string. If the resource is found,
 486     the function creates
 487     a new character array and copies the data into it. A pointer to this data is
 488     returned. If unsuccessful, @NULL is returned.
 489     The resource must be defined in the @c .rc file using the following syntax:
 490
 491     @code
 492     myResource TEXT file.ext
 493     @endcode
 494
 495     where @c file.ext is a file that the resource compiler can find.
 496     This function is available under Windows only.
 497
 498     @header{wx/utils.h}
 499 */
 500 wxString wxLoadUserResource(const wxString& resourceName,
 501                             const wxString& resourceType = "TEXT");
 502
 503 /**
 504     Returns the amount of free memory in bytes under environments which
 505     support it, and -1 if not supported or failed to perform measurement.
 506 */
 507 wxMemorySize wxGetFreeMemory();
 508
 509 //@{
 510 /**
 511     Copies the current host machine's name into the supplied buffer. Please note
 512     that the returned name is @e not fully qualified, i.e. it does not include
 513     the domain name.
 514     Under Windows or NT, this function first looks in the environment
 515     variable SYSTEM_NAME; if this is not found, the entry @b HostName
 516     in the @b wxWidgets section of the WIN.INI file is tried.
 517     The first variant of this function returns the hostname if successful or an
 518     empty string otherwise. The second (deprecated) function returns @true
 519     if successful, @false otherwise.
 520
 521     @see wxGetFullHostName()
 522
 523     @header{wx/utils.h}
 524 */
 525 wxString wxGetHostName();
 526 bool wxGetHostName(char* buf, int sz);
 527 //@}
 528
 529 /**
 530     Under X only, returns the current display name. See also wxSetDisplayName().
 531
 532     @header{wx/utils.h}
 533 */
 534 wxString wxGetDisplayName();
 535
 536 /**
 537     Returns the home directory for the given user. If the @a user is empty
 538     (default value), this function behaves like
 539     wxGetHomeDir() i.e. returns the current user home
 540     directory.
 541     If the home directory couldn't be determined, an empty string is returned.
 542
 543     @header{wx/utils.h}
 544 */
 545 wxString wxGetUserHome(const wxString& user = "");
 546
 547 //@{
 548 /**
 549     @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
 550     and it only takes the @c command argument,
 551     and returns a 3-element list @c ( status, output, errors ), where
 552     @c output and @c errors are array references.
 553     Executes another program in Unix or Windows.
 554     The first form takes a command string, such as @c "emacs file.txt".
 555     The second form takes an array of values: a command, any number of
 556     arguments, terminated by @NULL.
 557     The semantics of the third and fourth versions is different from the first two
 558     and is described in more details below.
 559     If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
 560     of control immediately returns. If it contains @c wxEXEC_SYNC, the current
 561     application waits until the other program has terminated.
 562     In the case of synchronous execution, the return value is the exit code of
 563     the process (which terminates by the moment the function returns) and will be
 564     -1 if the process couldn't be started and typically 0 if the process
 565     terminated successfully. Also, while waiting for the process to
 566     terminate, wxExecute will call wxYield(). Because of this, by
 567     default this function disables all application windows to avoid unexpected
 568     reentrancies which could result from the users interaction with the program
 569     while the child process is running. If you are sure that it is safe to not
 570     disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
 571     prevent this automatic disabling from happening.
 572     For asynchronous execution, however, the return value is the process id and
 573     zero value indicates that the command could not be executed. As an added
 574     complication, the return value of -1 in this case indicates that we didn't
 575     launch a new process, but connected to the running one (this can only happen in
 576     case of using DDE under Windows for command execution). In particular, in this,
 577     and only this, case the calling code will not get the notification about
 578     process termination.
 579     If callback isn't @NULL and if execution is asynchronous,
 580     wxProcess::OnTerminate will be called when
 581     the process finishes. Specifying this parameter also allows you to redirect the
 582     standard input and/or output of the process being launched by calling
 583     wxProcess::Redirect. If the child process IO is redirected,
 584     under Windows the process window is not shown by default (this avoids having to
 585     flush an unnecessary console for the processes which don't create any windows
 586     anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
 587     happening, i.e. with this flag the child process window will be shown normally.
 588     Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure
 589     that the new process is a group leader (this will create a new session if
 590     needed). Calling wxKill() passing wxKILL_CHILDREN will
 591     kill this process as well as all of its children (except those which have
 592     started their own session).
 593     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
 594     place while the child process is running. It should be only used for very
 595     short-lived processes as otherwise the application windows risk becoming
 596     unresponsive from the users point of view. As this flag only makes sense with
 597     @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
 598     is provided as a convenience.
 599     Finally, you may use the third overloaded version of this function to execute
 600     a process (always synchronously, the contents of @a flags is or'd with
 601     @c wxEXEC_SYNC) and capture its output in the array @e output. The
 602     fourth version adds the possibility to additionally capture the messages from
 603     standard error output in the @a errors array.
 604     @b NB: Currently wxExecute() can only be used from the main thread, calling
 605     this function from another thread will result in an assert failure in debug
 606     build and won't work.
 607
 608     @param command
 609         The command to execute and any parameters to pass to it as a
 610         single string.
 611     @param argv
 612         The command to execute should be the first element of this
 613         array, any additional ones are the command parameters and the array must be
 614         terminated with a @NULL pointer.
 615     @param flags
 616         Combination of bit masks wxEXEC_ASYNC,
 617         wxEXEC_SYNC and wxEXEC_NOHIDE
 618     @param callback
 619         An optional pointer to wxProcess
 620
 621     @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
 622
 623     @header{wx/utils.h}
 624 */
 625 long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC,
 626                 wxProcess* callback = NULL);
 627 wxPerl note: long wxExecute(char** argv,
 628                             int flags = wxEXEC_ASYNC,
 629                             wxProcess* callback = NULL);
 630 wxPerl note: long wxExecute(const wxString& command,
 631                             wxArrayString& output,
 632                             int flags = 0);
 633 wxPerl note: long wxExecute(const wxString& command,
 634                             wxArrayString& output,
 635                             wxArrayString& errors,
 636                             int flags = 0);
 637 //@}
 638
 639 /**
 640     Returns a string representing the current date and time.
 641
 642     @header{wx/utils.h}
 643 */
 644 wxString wxNow();
 645
 646 /**
 647     Returns @true if the operating system the program is running under is 64 bit.
 648     The check is performed at run-time and may differ from the value available at
 649     compile-time (at compile-time you can just check if @c sizeof(void*)==8)
 650     since the program could be running in emulation mode or in a mixed 32/64 bit
 651     system
 652     (bi-architecture operating system).
 653     Very important: this function is not 100% reliable on some systems given the
 654     fact
 655     that there isn't always a standard way to do a reliable check on the OS
 656     architecture.
 657
 658     @header{wx/utils.h}
 659 */
 660 bool wxIsPlatform64Bit();
 661
 662 /**
 663     Returns the number uniquely identifying the current process in the system.
 664     If an error occurs, 0 is returned.
 665
 666     @header{wx/utils.h}
 667 */
 668 unsigned long wxGetProcessId();
 669
 670 /**
 671     Equivalent to the Unix kill function: send the given signal @a sig to the
 672     process with PID @e pid. The valid signal values are
 673
 674     @code
 675     enum wxSignal
 676     {
 677         wxSIGNONE = 0,  // verify if the process exists under Unix
 678         wxSIGHUP,
 679         wxSIGINT,
 680         wxSIGQUIT,
 681         wxSIGILL,
 682         wxSIGTRAP,
 683         wxSIGABRT,
 684         wxSIGEMT,
 685         wxSIGFPE,
 686         wxSIGKILL,      // forcefully kill, dangerous!
 687         wxSIGBUS,
 688         wxSIGSEGV,
 689         wxSIGSYS,
 690         wxSIGPIPE,
 691         wxSIGALRM,
 692         wxSIGTERM       // terminate the process gently
 693     };
 694     @endcode
 695
 696     @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
 697     under both Unix and Windows but all the other signals are equivalent to
 698     @c wxSIGTERM under Windows.
 699     Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will
 700     be filled with an element of @c wxKillError enum:
 701
 702     @code
 703     enum wxKillError
 704     {
 705         wxKILL_OK,              // no error
 706         wxKILL_BAD_SIGNAL,      // no such signal
 707         wxKILL_ACCESS_DENIED,   // permission denied
 708         wxKILL_NO_PROCESS,      // no such process
 709         wxKILL_ERROR            // another, unspecified error
 710     };
 711     @endcode
 712
 713     The @a flags parameter can be wxKILL_NOCHILDREN (the default),
 714     or wxKILL_CHILDREN, in which case the child processes of this
 715     process will be killed too. Note that under Unix, for wxKILL_CHILDREN
 716     to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER
 717     to wxExecute.
 718
 719     @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
 720
 721     @header{wx/utils.h}
 722 */
 723 int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
 724             int flags = 0);
 725
 726 /**
 727     Returns the current state of the mouse.  Returns a wxMouseState
 728     instance that contains the current position of the mouse pointer in
 729     screen coordinates, as well as boolean values indicating the up/down
 730     status of the mouse buttons and the modifier keys.
 731
 732     @header{wx/utils.h}
 733 */
 734 wxMouseState wxGetMouseState();
 735
 736 //@{
 737 /**
 738     Copies the user's email address into the supplied buffer, by
 739     concatenating the values returned by wxGetFullHostName()
 740     and wxGetUserId().
 741     Returns @true if successful, @false otherwise.
 742
 743     @header{wx/utils.h}
 744 */
 745 wxString wxGetEmailAddress();
 746 bool wxGetEmailAddress(char* buf, int sz);
 747 //@}
 748
 749 /**
 750     Sleeps for the specified number of seconds.
 751
 752     @header{wx/utils.h}
 753 */
 754 void wxSleep(int secs);
 755
 756 /**
 757     Returns @true if the current platform is little endian (instead of big
 758     endian).
 759     The check is performed at run-time.
 760
 761     @see @ref overview_byteordermacros "Byte order macros"
 762
 763     @header{wx/utils.h}
 764 */
 765 bool wxIsPlatformLittleEndian();
 766
 767 /**
 768     Under X only, sets the current display name. This is the X host and display
 769     name such
 770     as "colonsay:0.0", and the function indicates which display should be used for
 771     creating
 772     windows from this point on. Setting the display within an application allows
 773     multiple
 774     displays to be used.
 775     See also wxGetDisplayName().
 776
 777     @header{wx/utils.h}
 778 */
 779 void wxSetDisplayName(const wxString& displayName);
 780