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