interface/utils.h

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