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