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