include/wx/utils.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/utils.h
   3 // Purpose:     Miscellaneous utilities
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_UTILS_H_
  13 #define _WX_UTILS_H_
  14
  15 // ----------------------------------------------------------------------------
  16 // headers
  17 // ----------------------------------------------------------------------------
  18
  19 #include "wx/object.h"
  20 #include "wx/list.h"
  21 #include "wx/filefn.h"
  22 #include "wx/hashmap.h"
  23 #include "wx/versioninfo.h"
  24 #include "wx/meta/implicitconversion.h"
  25
  26 #if wxUSE_GUI
  27     #include "wx/gdicmn.h"
  28     #include "wx/mousestate.h"
  29 #endif
  30
  31 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  32 class WXDLLIMPEXP_FWD_BASE wxArrayInt;
  33
  34 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
  35 // wxLongLong
  36 #include "wx/longlong.h"
  37
  38 // needed for wxOperatingSystemId, wxLinuxDistributionInfo
  39 #include "wx/platinfo.h"
  40
  41 #ifdef __WATCOMC__
  42     #include <direct.h>
  43 #elif defined(__X__)
  44     #include <dirent.h>
  45     #include <unistd.h>
  46 #endif
  47
  48 #include <stdio.h>
  49
  50 // ----------------------------------------------------------------------------
  51 // Forward declaration
  52 // ----------------------------------------------------------------------------
  53
  54 class WXDLLIMPEXP_FWD_BASE wxProcess;
  55 class WXDLLIMPEXP_FWD_CORE wxFrame;
  56 class WXDLLIMPEXP_FWD_CORE wxWindow;
  57 class WXDLLIMPEXP_FWD_CORE wxWindowList;
  58
  59 // ----------------------------------------------------------------------------
  60 // Arithmetic functions
  61 // ----------------------------------------------------------------------------
  62
  63 template<typename T1, typename T2>
  64 inline typename wxImplicitConversionType<T1,T2>::value
  65 wxMax(T1 a, T2 b)
  66 {
  67     typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
  68
  69     // Cast both operands to the same type before comparing them to avoid
  70     // warnings about signed/unsigned comparisons from some compilers:
  71     return static_cast<ResultType>(a) > static_cast<ResultType>(b) ? a : b;
  72 }
  73
  74 template<typename T1, typename T2>
  75 inline typename wxImplicitConversionType<T1,T2>::value
  76 wxMin(T1 a, T2 b)
  77 {
  78     typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
  79
  80     return static_cast<ResultType>(a) < static_cast<ResultType>(b) ? a : b;
  81 }
  82
  83 template<typename T1, typename T2, typename T3>
  84 inline typename wxImplicitConversionType3<T1,T2,T3>::value
  85 wxClip(T1 a, T2 b, T3 c)
  86 {
  87     typedef typename wxImplicitConversionType3<T1,T2,T3>::value ResultType;
  88
  89     if ( static_cast<ResultType>(a) < static_cast<ResultType>(b) )
  90         return b;
  91
  92     if ( static_cast<ResultType>(a) > static_cast<ResultType>(c) )
  93         return c;
  94
  95     return a;
  96 }
  97
  98 // ----------------------------------------------------------------------------
  99 // wxMemorySize
 100 // ----------------------------------------------------------------------------
 101
 102 // wxGetFreeMemory can return huge amount of memory on 32-bit platforms as well
 103 // so to always use long long for its result type on all platforms which
 104 // support it
 105 #if wxUSE_LONGLONG
 106     typedef wxLongLong wxMemorySize;
 107 #else
 108     typedef long wxMemorySize;
 109 #endif
 110
 111 // ----------------------------------------------------------------------------
 112 // String functions (deprecated, use wxString)
 113 // ----------------------------------------------------------------------------
 114
 115 #ifdef WXWIN_COMPATIBILITY_2_8
 116 // A shorter way of using strcmp
 117 wxDEPRECATED_INLINE(inline bool wxStringEq(const char *s1, const char *s2),
 118     return wxCRT_StrcmpA(s1, s2) == 0; )
 119
 120 #if wxUSE_UNICODE
 121 wxDEPRECATED_INLINE(inline bool wxStringEq(const wchar_t *s1, const wchar_t *s2),
 122     return wxCRT_StrcmpW(s1, s2) == 0; )
 123 #endif // wxUSE_UNICODE
 124
 125 #endif // WXWIN_COMPATIBILITY_2_8
 126
 127 // ----------------------------------------------------------------------------
 128 // Miscellaneous functions
 129 // ----------------------------------------------------------------------------
 130
 131 // Sound the bell
 132 #if !defined __EMX__ && \
 133     (defined __WXMOTIF__ || defined __WXGTK__ || defined __WXX11__)
 134 WXDLLIMPEXP_CORE void wxBell();
 135 #else
 136 WXDLLIMPEXP_BASE void wxBell();
 137 #endif
 138
 139 #if wxUSE_MSGDLG
 140 // Show wxWidgets information
 141 WXDLLIMPEXP_CORE void wxInfoMessageBox(wxWindow* parent);
 142 #endif // wxUSE_MSGDLG
 143
 144 WXDLLIMPEXP_CORE wxVersionInfo wxGetLibraryVersionInfo();
 145
 146 // Get OS description as a user-readable string
 147 WXDLLIMPEXP_BASE wxString wxGetOsDescription();
 148
 149 // Get OS version
 150 WXDLLIMPEXP_BASE wxOperatingSystemId wxGetOsVersion(int *majorVsn = NULL,
 151                                                     int *minorVsn = NULL);
 152
 153 // Get platform endianness
 154 WXDLLIMPEXP_BASE bool wxIsPlatformLittleEndian();
 155
 156 // Get platform architecture
 157 WXDLLIMPEXP_BASE bool wxIsPlatform64Bit();
 158
 159 #ifdef __LINUX__
 160 // Get linux-distro informations
 161 WXDLLIMPEXP_BASE wxLinuxDistributionInfo wxGetLinuxDistributionInfo();
 162 #endif
 163
 164 // Return a string with the current date/time
 165 WXDLLIMPEXP_BASE wxString wxNow();
 166
 167 // Return path where wxWidgets is installed (mostly useful in Unices)
 168 WXDLLIMPEXP_BASE const wxChar *wxGetInstallPrefix();
 169 // Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
 170 WXDLLIMPEXP_BASE wxString wxGetDataDir();
 171
 172 #if wxUSE_GUI
 173
 174 // Get the state of a key (true if pressed, false if not)
 175 // This is generally most useful getting the state of
 176 // the modifier or toggle keys.
 177 WXDLLIMPEXP_CORE bool wxGetKeyState(wxKeyCode key);
 178
 179 // Don't synthesize KeyUp events holding down a key and producing
 180 // KeyDown events with autorepeat. On by default and always on
 181 // in wxMSW.
 182 WXDLLIMPEXP_CORE bool wxSetDetectableAutoRepeat( bool flag );
 183
 184 // Returns the current state of the mouse position, buttons and modifers
 185 WXDLLIMPEXP_CORE wxMouseState wxGetMouseState();
 186
 187 #endif // wxUSE_GUI
 188
 189 // ----------------------------------------------------------------------------
 190 // wxPlatform
 191 // ----------------------------------------------------------------------------
 192
 193 /*
 194  * Class to make it easier to specify platform-dependent values
 195  *
 196  * Examples:
 197  *  long val = wxPlatform::If(wxMac, 1).ElseIf(wxGTK, 2).ElseIf(stPDA, 5).Else(3);
 198  *  wxString strVal = wxPlatform::If(wxMac, wxT("Mac")).ElseIf(wxMSW, wxT("MSW")).Else(wxT("Other"));
 199  *
 200  * A custom platform symbol:
 201  *
 202  *  #define stPDA 100
 203  *  #ifdef __WXWINCE__
 204  *      wxPlatform::AddPlatform(stPDA);
 205  *  #endif
 206  *
 207  *  long windowStyle = wxCAPTION | (long) wxPlatform::IfNot(stPDA, wxRESIZE_BORDER);
 208  *
 209  */
 210
 211 class WXDLLIMPEXP_BASE wxPlatform
 212 {
 213 public:
 214     wxPlatform() { Init(); }
 215     wxPlatform(const wxPlatform& platform) { Copy(platform); }
 216     void operator = (const wxPlatform& platform) { if (&platform != this) Copy(platform); }
 217     void Copy(const wxPlatform& platform);
 218
 219     // Specify an optional default value
 220     wxPlatform(int defValue) { Init(); m_longValue = (long)defValue; }
 221     wxPlatform(long defValue) { Init(); m_longValue = defValue; }
 222     wxPlatform(const wxString& defValue) { Init(); m_stringValue = defValue; }
 223     wxPlatform(double defValue) { Init(); m_doubleValue = defValue; }
 224
 225     static wxPlatform If(int platform, long value);
 226     static wxPlatform IfNot(int platform, long value);
 227     wxPlatform& ElseIf(int platform, long value);
 228     wxPlatform& ElseIfNot(int platform, long value);
 229     wxPlatform& Else(long value);
 230
 231     static wxPlatform If(int platform, int value) { return If(platform, (long)value); }
 232     static wxPlatform IfNot(int platform, int value) { return IfNot(platform, (long)value); }
 233     wxPlatform& ElseIf(int platform, int value) { return ElseIf(platform, (long) value); }
 234     wxPlatform& ElseIfNot(int platform, int value) { return ElseIfNot(platform, (long) value); }
 235     wxPlatform& Else(int value) { return Else((long) value); }
 236
 237     static wxPlatform If(int platform, double value);
 238     static wxPlatform IfNot(int platform, double value);
 239     wxPlatform& ElseIf(int platform, double value);
 240     wxPlatform& ElseIfNot(int platform, double value);
 241     wxPlatform& Else(double value);
 242
 243     static wxPlatform If(int platform, const wxString& value);
 244     static wxPlatform IfNot(int platform, const wxString& value);
 245     wxPlatform& ElseIf(int platform, const wxString& value);
 246     wxPlatform& ElseIfNot(int platform, const wxString& value);
 247     wxPlatform& Else(const wxString& value);
 248
 249     long GetInteger() const { return m_longValue; }
 250     const wxString& GetString() const { return m_stringValue; }
 251     double GetDouble() const { return m_doubleValue; }
 252
 253     operator int() const { return (int) GetInteger(); }
 254     operator long() const { return GetInteger(); }
 255     operator double() const { return GetDouble(); }
 256     operator const wxString&() const { return GetString(); }
 257
 258     static void AddPlatform(int platform);
 259     static bool Is(int platform);
 260     static void ClearPlatforms();
 261
 262 private:
 263
 264     void Init() { m_longValue = 0; m_doubleValue = 0.0; }
 265
 266     long                m_longValue;
 267     double              m_doubleValue;
 268     wxString            m_stringValue;
 269     static wxArrayInt*  sm_customPlatforms;
 270 };
 271
 272 /// Function for testing current platform
 273 inline bool wxPlatformIs(int platform) { return wxPlatform::Is(platform); }
 274
 275 // ----------------------------------------------------------------------------
 276 // Window ID management
 277 // ----------------------------------------------------------------------------
 278
 279 // Ensure subsequent IDs don't clash with this one
 280 WXDLLIMPEXP_BASE void wxRegisterId(long id);
 281
 282 // Return the current ID
 283 WXDLLIMPEXP_BASE long wxGetCurrentId();
 284
 285 // Generate a unique ID
 286 WXDLLIMPEXP_BASE long wxNewId();
 287
 288 // ----------------------------------------------------------------------------
 289 // Various conversions
 290 // ----------------------------------------------------------------------------
 291
 292 // Convert 2-digit hex number to decimal
 293 WXDLLIMPEXP_BASE int wxHexToDec(const wxString& buf);
 294
 295 // Convert 2-digit hex number to decimal
 296 inline int wxHexToDec(const char* buf)
 297 {
 298     int firstDigit, secondDigit;
 299
 300     if (buf[0] >= 'A')
 301         firstDigit = buf[0] - 'A' + 10;
 302     else
 303         firstDigit = buf[0] - '0';
 304
 305     if (buf[1] >= 'A')
 306         secondDigit = buf[1] - 'A' + 10;
 307     else
 308         secondDigit = buf[1] - '0';
 309
 310     return (firstDigit & 0xF) * 16 + (secondDigit & 0xF );
 311 }
 312
 313
 314 // Convert decimal integer to 2-character hex string
 315 WXDLLIMPEXP_BASE void wxDecToHex(int dec, wxChar *buf);
 316 WXDLLIMPEXP_BASE void wxDecToHex(int dec, char* ch1, char* ch2);
 317 WXDLLIMPEXP_BASE wxString wxDecToHex(int dec);
 318
 319 // ----------------------------------------------------------------------------
 320 // Process management
 321 // ----------------------------------------------------------------------------
 322
 323 // NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
 324 //     be 0 and 1, don't change!
 325
 326 enum
 327 {
 328     // execute the process asynchronously
 329     wxEXEC_ASYNC    = 0,
 330
 331     // execute it synchronously, i.e. wait until it finishes
 332     wxEXEC_SYNC     = 1,
 333
 334     // under Windows, don't hide the child even if it's IO is redirected (this
 335     // is done by default)
 336     wxEXEC_NOHIDE   = 2,
 337
 338     // under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill
 339     // kills all children as well as pid
 340     wxEXEC_MAKE_GROUP_LEADER = 4,
 341
 342     // by default synchronous execution disables all program windows to avoid
 343     // that the user interacts with the program while the child process is
 344     // running, you can use this flag to prevent this from happening
 345     wxEXEC_NODISABLE = 8,
 346
 347     // by default, the event loop is run while waiting for synchronous execution
 348     // to complete and this flag can be used to simply block the main process
 349     // until the child process finishes
 350     wxEXEC_NOEVENTS = 16,
 351
 352     // convenient synonym for flags given system()-like behaviour
 353     wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
 354 };
 355
 356 // Map storing environment variables.
 357 typedef wxStringToStringHashMap wxEnvVariableHashMap;
 358
 359 // Used to pass additional parameters for child process to wxExecute(). Could
 360 // be extended with other fields later.
 361 struct wxExecuteEnv
 362 {
 363     wxString cwd;               // If empty, CWD is not changed.
 364     wxEnvVariableHashMap env;   // If empty, environment is unchanged.
 365 };
 366
 367 // Execute another program.
 368 //
 369 // If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
 370 // process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
 371 // failure and the PID of the launched process if ok.
 372 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
 373                                 int flags = wxEXEC_ASYNC,
 374                                 wxProcess *process = NULL,
 375                                 const wxExecuteEnv *env = NULL);
 376 WXDLLIMPEXP_BASE long wxExecute(char **argv,
 377                                 int flags = wxEXEC_ASYNC,
 378                                 wxProcess *process = NULL,
 379                                 const wxExecuteEnv *env = NULL);
 380 #if wxUSE_UNICODE
 381 WXDLLIMPEXP_BASE long wxExecute(wchar_t **argv,
 382                                 int flags = wxEXEC_ASYNC,
 383                                 wxProcess *process = NULL,
 384                                 const wxExecuteEnv *env = NULL);
 385 #endif // wxUSE_UNICODE
 386
 387 // execute the command capturing its output into an array line by line, this is
 388 // always synchronous
 389 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
 390                                 wxArrayString& output,
 391                                 int flags = 0,
 392                                 const wxExecuteEnv *env = NULL);
 393
 394 // also capture stderr (also synchronous)
 395 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
 396                                 wxArrayString& output,
 397                                 wxArrayString& error,
 398                                 int flags = 0,
 399                                 const wxExecuteEnv *env = NULL);
 400
 401 #if defined(__WXMSW__) && wxUSE_IPC
 402 // ask a DDE server to execute the DDE request with given parameters
 403 WXDLLIMPEXP_BASE bool wxExecuteDDE(const wxString& ddeServer,
 404                                    const wxString& ddeTopic,
 405                                    const wxString& ddeCommand);
 406 #endif // __WXMSW__ && wxUSE_IPC
 407
 408 enum wxSignal
 409 {
 410     wxSIGNONE = 0,  // verify if the process exists under Unix
 411     wxSIGHUP,
 412     wxSIGINT,
 413     wxSIGQUIT,
 414     wxSIGILL,
 415     wxSIGTRAP,
 416     wxSIGABRT,
 417     wxSIGIOT = wxSIGABRT,   // another name
 418     wxSIGEMT,
 419     wxSIGFPE,
 420     wxSIGKILL,
 421     wxSIGBUS,
 422     wxSIGSEGV,
 423     wxSIGSYS,
 424     wxSIGPIPE,
 425     wxSIGALRM,
 426     wxSIGTERM
 427
 428     // further signals are different in meaning between different Unix systems
 429 };
 430
 431 enum wxKillError
 432 {
 433     wxKILL_OK,              // no error
 434     wxKILL_BAD_SIGNAL,      // no such signal
 435     wxKILL_ACCESS_DENIED,   // permission denied
 436     wxKILL_NO_PROCESS,      // no such process
 437     wxKILL_ERROR            // another, unspecified error
 438 };
 439
 440 enum wxKillFlags
 441 {
 442     wxKILL_NOCHILDREN = 0,  // don't kill children
 443     wxKILL_CHILDREN = 1     // kill children
 444 };
 445
 446 enum wxShutdownFlags
 447 {
 448     wxSHUTDOWN_FORCE    = 1,// can be combined with other flags (MSW-only)
 449     wxSHUTDOWN_POWEROFF = 2,// power off the computer
 450     wxSHUTDOWN_REBOOT   = 4,// shutdown and reboot
 451     wxSHUTDOWN_LOGOFF   = 8 // close session (currently MSW-only)
 452 };
 453
 454 // Shutdown or reboot the PC
 455 WXDLLIMPEXP_BASE bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
 456
 457 // send the given signal to the process (only NONE and KILL are supported under
 458 // Windows, all others mean TERM), return 0 if ok and -1 on error
 459 //
 460 // return detailed error in rc if not NULL
 461 WXDLLIMPEXP_BASE int wxKill(long pid,
 462                        wxSignal sig = wxSIGTERM,
 463                        wxKillError *rc = NULL,
 464                        int flags = wxKILL_NOCHILDREN);
 465
 466 // Execute a command in an interactive shell window (always synchronously)
 467 // If no command then just the shell
 468 WXDLLIMPEXP_BASE bool wxShell(const wxString& command = wxEmptyString);
 469
 470 // As wxShell(), but must give a (non interactive) command and its output will
 471 // be returned in output array
 472 WXDLLIMPEXP_BASE bool wxShell(const wxString& command, wxArrayString& output);
 473
 474 // Sleep for nSecs seconds
 475 WXDLLIMPEXP_BASE void wxSleep(int nSecs);
 476
 477 // Sleep for a given amount of milliseconds
 478 WXDLLIMPEXP_BASE void wxMilliSleep(unsigned long milliseconds);
 479
 480 // Sleep for a given amount of microseconds
 481 WXDLLIMPEXP_BASE void wxMicroSleep(unsigned long microseconds);
 482
 483 #if WXWIN_COMPATIBILITY_2_8
 484 // Sleep for a given amount of milliseconds (old, bad name), use wxMilliSleep
 485 wxDEPRECATED( WXDLLIMPEXP_BASE void wxUsleep(unsigned long milliseconds) );
 486 #endif
 487
 488 // Get the process id of the current process
 489 WXDLLIMPEXP_BASE unsigned long wxGetProcessId();
 490
 491 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
 492 WXDLLIMPEXP_BASE wxMemorySize wxGetFreeMemory();
 493
 494 #if wxUSE_ON_FATAL_EXCEPTION
 495
 496 // should wxApp::OnFatalException() be called?
 497 WXDLLIMPEXP_BASE bool wxHandleFatalExceptions(bool doit = true);
 498
 499 #endif // wxUSE_ON_FATAL_EXCEPTION
 500
 501 // ----------------------------------------------------------------------------
 502 // Environment variables
 503 // ----------------------------------------------------------------------------
 504
 505 // returns true if variable exists (value may be NULL if you just want to check
 506 // for this)
 507 WXDLLIMPEXP_BASE bool wxGetEnv(const wxString& var, wxString *value);
 508
 509 // set the env var name to the given value, return true on success
 510 WXDLLIMPEXP_BASE bool wxSetEnv(const wxString& var, const wxString& value);
 511
 512 // remove the env var from environment
 513 WXDLLIMPEXP_BASE bool wxUnsetEnv(const wxString& var);
 514
 515 #if WXWIN_COMPATIBILITY_2_8
 516 inline bool wxSetEnv(const wxString& var, const char *value)
 517     { return wxSetEnv(var, wxString(value)); }
 518 inline bool wxSetEnv(const wxString& var, const wchar_t *value)
 519     { return wxSetEnv(var, wxString(value)); }
 520 template<typename T>
 521 inline bool wxSetEnv(const wxString& var, const wxScopedCharTypeBuffer<T>& value)
 522     { return wxSetEnv(var, wxString(value)); }
 523 inline bool wxSetEnv(const wxString& var, const wxCStrData& value)
 524     { return wxSetEnv(var, wxString(value)); }
 525
 526 // this one is for passing NULL directly - don't use it, use wxUnsetEnv instead
 527 wxDEPRECATED( inline bool wxSetEnv(const wxString& var, int value) );
 528 inline bool wxSetEnv(const wxString& var, int value)
 529 {
 530     wxASSERT_MSG( value == 0, "using non-NULL integer as string?" );
 531
 532     wxUnusedVar(value); // fix unused parameter warning in release build
 533
 534     return wxUnsetEnv(var);
 535 }
 536 #endif // WXWIN_COMPATIBILITY_2_8
 537
 538 // Retrieve the complete environment by filling specified map.
 539 // Returns true on success or false if an error occurred.
 540 WXDLLIMPEXP_BASE bool wxGetEnvMap(wxEnvVariableHashMap *map);
 541
 542 // ----------------------------------------------------------------------------
 543 // Network and username functions.
 544 // ----------------------------------------------------------------------------
 545
 546 // NB: "char *" functions are deprecated, use wxString ones!
 547
 548 // Get eMail address
 549 WXDLLIMPEXP_BASE bool wxGetEmailAddress(wxChar *buf, int maxSize);
 550 WXDLLIMPEXP_BASE wxString wxGetEmailAddress();
 551
 552 // Get hostname.
 553 WXDLLIMPEXP_BASE bool wxGetHostName(wxChar *buf, int maxSize);
 554 WXDLLIMPEXP_BASE wxString wxGetHostName();
 555
 556 // Get FQDN
 557 WXDLLIMPEXP_BASE wxString wxGetFullHostName();
 558 WXDLLIMPEXP_BASE bool wxGetFullHostName(wxChar *buf, int maxSize);
 559
 560 // Get user ID e.g. jacs (this is known as login name under Unix)
 561 WXDLLIMPEXP_BASE bool wxGetUserId(wxChar *buf, int maxSize);
 562 WXDLLIMPEXP_BASE wxString wxGetUserId();
 563
 564 // Get user name e.g. Julian Smart
 565 WXDLLIMPEXP_BASE bool wxGetUserName(wxChar *buf, int maxSize);
 566 WXDLLIMPEXP_BASE wxString wxGetUserName();
 567
 568 // Get current Home dir and copy to dest (returns pstr->c_str())
 569 WXDLLIMPEXP_BASE wxString wxGetHomeDir();
 570 WXDLLIMPEXP_BASE const wxChar* wxGetHomeDir(wxString *pstr);
 571
 572 // Get the user's (by default use the current user name) home dir,
 573 // return empty string on error
 574 WXDLLIMPEXP_BASE wxString wxGetUserHome(const wxString& user = wxEmptyString);
 575
 576
 577 #if wxUSE_LONGLONG
 578     typedef wxLongLong wxDiskspaceSize_t;
 579 #else
 580     typedef long wxDiskspaceSize_t;
 581 #endif
 582
 583 // get number of total/free bytes on the disk where path belongs
 584 WXDLLIMPEXP_BASE bool wxGetDiskSpace(const wxString& path,
 585                                      wxDiskspaceSize_t *pTotal = NULL,
 586                                      wxDiskspaceSize_t *pFree = NULL);
 587
 588
 589
 590 extern "C"
 591 {
 592 typedef int (wxCMPFUNC_CONV *CMPFUNCDATA)(const void* pItem1, const void* pItem2, const void* user_data);
 593 }
 594
 595
 596 WXDLLIMPEXP_BASE void wxQsort(void *const pbase, size_t total_elems,
 597                               size_t size, CMPFUNCDATA cmp, const void* user_data);
 598
 599
 600 #if wxUSE_GUI // GUI only things from now on
 601
 602 // ----------------------------------------------------------------------------
 603 // Launch default browser
 604 // ----------------------------------------------------------------------------
 605
 606 // flags for wxLaunchDefaultBrowser
 607 enum
 608 {
 609     wxBROWSER_NEW_WINDOW   = 0x01,
 610     wxBROWSER_NOBUSYCURSOR = 0x02
 611 };
 612
 613 // Launch url in the user's default internet browser
 614 WXDLLIMPEXP_CORE bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 615
 616 // Launch document in the user's default application
 617 WXDLLIMPEXP_CORE bool wxLaunchDefaultApplication(const wxString& path, int flags = 0);
 618
 619 // ----------------------------------------------------------------------------
 620 // Menu accelerators related things
 621 // ----------------------------------------------------------------------------
 622
 623 // flags for wxStripMenuCodes
 624 enum
 625 {
 626     // strip '&' characters
 627     wxStrip_Mnemonics = 1,
 628
 629     // strip everything after '\t'
 630     wxStrip_Accel = 2,
 631
 632     // strip everything (this is the default)
 633     wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
 634 };
 635
 636 // strip mnemonics and/or accelerators from the label
 637 WXDLLIMPEXP_CORE wxString
 638 wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
 639
 640 #if WXWIN_COMPATIBILITY_2_6
 641 // obsolete and deprecated version, do not use, use the above overload instead
 642 wxDEPRECATED(
 643     WXDLLIMPEXP_CORE wxChar* wxStripMenuCodes(const wxChar *in, wxChar *out = NULL)
 644 );
 645
 646 #if wxUSE_ACCEL
 647 class WXDLLIMPEXP_FWD_CORE wxAcceleratorEntry;
 648
 649 // use wxAcceleratorEntry::Create() or FromString() methods instead
 650 wxDEPRECATED(
 651     WXDLLIMPEXP_CORE wxAcceleratorEntry *wxGetAccelFromString(const wxString& label)
 652 );
 653 #endif // wxUSE_ACCEL
 654
 655 #endif // WXWIN_COMPATIBILITY_2_6
 656
 657 // ----------------------------------------------------------------------------
 658 // Window search
 659 // ----------------------------------------------------------------------------
 660
 661 // Returns menu item id or wxNOT_FOUND if none.
 662 WXDLLIMPEXP_CORE int wxFindMenuItemId(wxFrame *frame, const wxString& menuString, const wxString& itemString);
 663
 664 // Find the wxWindow at the given point. wxGenericFindWindowAtPoint
 665 // is always present but may be less reliable than a native version.
 666 WXDLLIMPEXP_CORE wxWindow* wxGenericFindWindowAtPoint(const wxPoint& pt);
 667 WXDLLIMPEXP_CORE wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
 668
 669 // NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
 670 //
 671 // Find the window/widget with the given title or label.
 672 // Pass a parent to begin the search from, or NULL to look through
 673 // all windows.
 674 WXDLLIMPEXP_CORE wxWindow* wxFindWindowByLabel(const wxString& title, wxWindow *parent = NULL);
 675
 676 // NB: this function is obsolete, use wxWindow::FindWindowByName() instead
 677 //
 678 // Find window by name, and if that fails, by label.
 679 WXDLLIMPEXP_CORE wxWindow* wxFindWindowByName(const wxString& name, wxWindow *parent = NULL);
 680
 681 // ----------------------------------------------------------------------------
 682 // Message/event queue helpers
 683 // ----------------------------------------------------------------------------
 684
 685 // Yield to other apps/messages and disable user input
 686 WXDLLIMPEXP_CORE bool wxSafeYield(wxWindow *win = NULL, bool onlyIfNeeded = false);
 687
 688 // Enable or disable input to all top level windows
 689 WXDLLIMPEXP_CORE void wxEnableTopLevelWindows(bool enable = true);
 690
 691 // Check whether this window wants to process messages, e.g. Stop button
 692 // in long calculations.
 693 WXDLLIMPEXP_CORE bool wxCheckForInterrupt(wxWindow *wnd);
 694
 695 // Consume all events until no more left
 696 WXDLLIMPEXP_CORE void wxFlushEvents();
 697
 698 // a class which disables all windows (except, may be, the given one) in its
 699 // ctor and enables them back in its dtor
 700 class WXDLLIMPEXP_CORE wxWindowDisabler
 701 {
 702 public:
 703     // this ctor conditionally disables all windows: if the argument is false,
 704     // it doesn't do anything
 705     wxWindowDisabler(bool disable = true);
 706
 707     // ctor disables all windows except winToSkip
 708     wxWindowDisabler(wxWindow *winToSkip);
 709
 710     // dtor enables back all windows disabled by the ctor
 711     ~wxWindowDisabler();
 712
 713 private:
 714     // disable all windows except the given one (used by both ctors)
 715     void DoDisable(wxWindow *winToSkip = NULL);
 716
 717
 718     wxWindowList *m_winDisabled;
 719     bool m_disabled;
 720
 721     wxDECLARE_NO_COPY_CLASS(wxWindowDisabler);
 722 };
 723
 724 // ----------------------------------------------------------------------------
 725 // Cursors
 726 // ----------------------------------------------------------------------------
 727
 728 // Set the cursor to the busy cursor for all windows
 729 WXDLLIMPEXP_CORE void wxBeginBusyCursor(const wxCursor *cursor = wxHOURGLASS_CURSOR);
 730
 731 // Restore cursor to normal
 732 WXDLLIMPEXP_CORE void wxEndBusyCursor();
 733
 734 // true if we're between the above two calls
 735 WXDLLIMPEXP_CORE bool wxIsBusy();
 736
 737 // Convenience class so we can just create a wxBusyCursor object on the stack
 738 class WXDLLIMPEXP_CORE wxBusyCursor
 739 {
 740 public:
 741     wxBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR)
 742         { wxBeginBusyCursor(cursor); }
 743     ~wxBusyCursor()
 744         { wxEndBusyCursor(); }
 745
 746     // FIXME: These two methods are currently only implemented (and needed?)
 747     //        in wxGTK.  BusyCursor handling should probably be moved to
 748     //        common code since the wxGTK and wxMSW implementations are very
 749     //        similar except for wxMSW using HCURSOR directly instead of
 750     //        wxCursor..  -- RL.
 751     static const wxCursor &GetStoredCursor();
 752     static const wxCursor GetBusyCursor();
 753 };
 754
 755 void WXDLLIMPEXP_CORE wxGetMousePosition( int* x, int* y );
 756
 757 // ----------------------------------------------------------------------------
 758 // X11 Display access
 759 // ----------------------------------------------------------------------------
 760
 761 #if defined(__X__) || defined(__WXGTK__)
 762
 763 #ifdef __WXGTK__
 764     WXDLLIMPEXP_CORE void *wxGetDisplay();
 765 #endif
 766
 767 #ifdef __X__
 768     WXDLLIMPEXP_CORE WXDisplay *wxGetDisplay();
 769     WXDLLIMPEXP_CORE bool wxSetDisplay(const wxString& display_name);
 770     WXDLLIMPEXP_CORE wxString wxGetDisplayName();
 771 #endif // X or GTK+
 772
 773 // use this function instead of the functions above in implementation code
 774 inline struct _XDisplay *wxGetX11Display()
 775 {
 776     return (_XDisplay *)wxGetDisplay();
 777 }
 778
 779 #endif // X11 || wxGTK
 780
 781 #endif // wxUSE_GUI
 782
 783 // ----------------------------------------------------------------------------
 784 // wxYield(): these functions are obsolete, please use wxApp methods instead!
 785 // ----------------------------------------------------------------------------
 786
 787 // avoid redeclaring this function here if it had been already declated by
 788 // wx/app.h, this results in warnings from g++ with -Wredundant-decls
 789 #ifndef wx_YIELD_DECLARED
 790 #define wx_YIELD_DECLARED
 791
 792 // Yield to other apps/messages
 793 WXDLLIMPEXP_CORE bool wxYield();
 794
 795 #endif // wx_YIELD_DECLARED
 796
 797 // Like wxYield, but fails silently if the yield is recursive.
 798 WXDLLIMPEXP_CORE bool wxYieldIfNeeded();
 799
 800 // ----------------------------------------------------------------------------
 801 // Windows resources access
 802 // ----------------------------------------------------------------------------
 803
 804 // MSW only: get user-defined resource from the .res file.
 805 #ifdef __WXMSW__
 806     // default resource type for wxLoadUserResource()
 807     extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxUserResourceStr;
 808
 809     // Return the pointer to the resource data. This pointer is read-only, use
 810     // the overload below if you need to modify the data.
 811     //
 812     // Returns true on success, false on failure. Doesn't log an error message
 813     // if the resource is not found (because this could be expected) but does
 814     // log one if any other error occurs.
 815     WXDLLIMPEXP_BASE bool
 816     wxLoadUserResource(const void **outData,
 817                        size_t *outLen,
 818                        const wxString& resourceName,
 819                        const wxString& resourceType = wxUserResourceStr,
 820                        WXHINSTANCE module = 0);
 821
 822     // This function allocates a new buffer and makes a copy of the resource
 823     // data, remember to delete[] the buffer. And avoid using it entirely if
 824     // the overload above can be used.
 825     //
 826     // Returns NULL on failure.
 827     WXDLLIMPEXP_BASE char*
 828     wxLoadUserResource(const wxString& resourceName,
 829                        const wxString& resourceType = wxUserResourceStr,
 830                        int* pLen = NULL,
 831                        WXHINSTANCE module = 0);
 832 #endif // MSW
 833
 834 #endif
 835     // _WX_UTILSH__