interface/platinfo.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        platinfo.h
   3 // Purpose:     interface of wxPlatformInfo
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPlatformInfo
  11     @wxheader{platinfo.h}
  12
  13     This class holds informations about the operating system and the toolkit that
  14     the application is running under and some basic architecture info of the machine
  15     where it's running.
  16
  17     @library{wxbase}
  18     @category{misc}
  19
  20     @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(),
  21     wxAppTraits
  22
  23     <b>Data structures:</b>
  24
  25     The following are the operating systems which are recognized by wxWidgets and
  26     whose version can be detected at run-time.
  27     The values of the constants are chosen so that they can be combined as flags;
  28     this allows to check for operating system families like
  29     e.g. wxOS_MAC and wxOS_UNIX.
  30
  31     @code
  32
  33     enum wxOperatingSystemId
  34     {
  35         wxOS_UNKNOWN = 0,                 // returned on error
  36
  37         wxOS_MAC_OS         = 1 << 0,     // Apple Mac OS 8/9/X with Mac paths
  38         wxOS_MAC_OSX_DARWIN = 1 << 1,     // Apple Mac OS X with Unix paths
  39         wxOS_MAC = wxOS_MAC_OS|wxOS_MAC_OSX_DARWIN,
  40
  41         wxOS_WINDOWS_9X     = 1 << 2,     // Windows 9x family (95/98/ME)
  42         wxOS_WINDOWS_NT     = 1 << 3,     // Windows NT family (NT/2000/XP)
  43         wxOS_WINDOWS_MICRO  = 1 << 4,     // MicroWindows
  44         wxOS_WINDOWS_CE     = 1 << 5,     // Windows CE (Window Mobile)
  45         wxOS_WINDOWS = wxOS_WINDOWS_9X      |
  46                        wxOS_WINDOWS_NT      |
  47                        wxOS_WINDOWS_MICRO   |
  48                        wxOS_WINDOWS_CE,
  49
  50         wxOS_UNIX_LINUX     = 1 << 6,       // Linux
  51         wxOS_UNIX_FREEBSD   = 1 << 7,       // FreeBSD
  52         wxOS_UNIX_OPENBSD   = 1 << 8,       // OpenBSD
  53         wxOS_UNIX_NETBSD    = 1 << 9,       // NetBSD
  54         wxOS_UNIX_SOLARIS   = 1 << 10,      // SunOS
  55         wxOS_UNIX_AIX       = 1 << 11,      // AIX
  56         wxOS_UNIX_HPUX      = 1 << 12,      // HP/UX
  57         wxOS_UNIX = wxOS_UNIX_LINUX     |
  58                     wxOS_UNIX_FREEBSD   |
  59                     wxOS_UNIX_OPENBSD   |
  60                     wxOS_UNIX_NETBSD    |
  61                     wxOS_UNIX_SOLARIS   |
  62                     wxOS_UNIX_AIX       |
  63                     wxOS_UNIX_HPUX,
  64
  65         wxOS_DOS            = 1 << 15,      // Microsoft DOS
  66         wxOS_OS2            = 1 << 16       // OS/2
  67     };
  68
  69     @endcode
  70
  71     The list of wxWidgets ports.
  72     Some of them can be used with more than a single (native) toolkit;
  73     e.g. wxWinCE port sources can be used with smartphones, pocket PCs
  74     and handheld devices SDKs.
  75
  76     @code
  77
  78     enum wxPortId
  79     {
  80         wxPORT_UNKNOWN  = 0,            // returned on error
  81
  82         wxPORT_BASE     = 1 << 0,       // wxBase, no native toolkit used
  83
  84         wxPORT_MSW      = 1 << 1,       // wxMSW, native toolkit is Windows API
  85         wxPORT_MOTIF    = 1 << 2,       // wxMotif, using [Open]Motif or Lesstif
  86         wxPORT_GTK      = 1 << 3,       // wxGTK, using GTK+ 1.x, 2.x, GPE or Maemo
  87         wxPORT_MGL      = 1 << 4,       // wxMGL, using wxUniversal
  88         wxPORT_X11      = 1 << 5,       // wxX11, using wxUniversal
  89         wxPORT_OS2      = 1 << 6,       // wxOS2, using OS/2 Presentation Manager
  90         wxPORT_MAC      = 1 << 7,       // wxMac, using Carbon or Classic Mac API
  91         wxPORT_COCOA    = 1 << 8,       // wxCocoa, using Cocoa NextStep/Mac API
  92         wxPORT_WINCE    = 1 << 9,       // wxWinCE, toolkit is WinCE SDK API
  93         wxPORT_PALMOS   = 1 << 10,      // wxPalmOS, toolkit is PalmOS API
  94         wxPORT_DFB      = 1 << 11       // wxDFB, using wxUniversal
  95     };
  96
  97     @endcode
  98
  99     The architecture of the operating system
 100     (regardless of the build environment of wxWidgets library
 101     - see wxIsPlatform64bit documentation for more info).
 102
 103     @code
 104
 105     enum wxArchitecture
 106     {
 107         wxARCH_INVALID = -1,        // returned on error
 108
 109         wxARCH_32,                  // 32 bit
 110         wxARCH_64,
 111
 112         wxARCH_MAX
 113     }
 114
 115     @endcode
 116
 117     The endian-ness of the machine.
 118
 119     @code
 120
 121     enum wxEndianness
 122     {
 123         wxENDIAN_INVALID = -1,      // returned on error
 124
 125         wxENDIAN_BIG,               // 4321
 126         wxENDIAN_LITTLE,            // 1234
 127         wxENDIAN_PDP,               // 3412
 128
 129         wxENDIAN_MAX
 130     }
 131
 132     @endcode
 133
 134
 135 */
 136 class wxPlatformInfo : public wxObject
 137 {
 138 public:
 139
 140     /**
 141         Initializes the instance with the values corresponding to the currently
 142         running platform.
 143
 144         This is a fast operation because it only requires to copy the values
 145         internally cached for the currently running platform.
 146
 147         @see Get()
 148     */
 149     wxPlatformInfo();
 150
 151     /**
 152         Initializes the object using given values.
 153     */
 154     wxPlatformInfo(wxPortId pid = wxPORT_UNKNOWN,
 155                    int tkMajor = -1,
 156                    int tkMinor = -1,
 157                    wxOperatingSystemId id = wxOS_UNKNOWN,
 158                    int osMajor = -1,
 159                    int osMinor = -1,
 160                    wxArchitecture arch = wxARCH_INVALID,
 161                    wxEndianness endian = wxENDIAN_INVALID);
 162
 163
 164     /**
 165         Returns @true if the OS version is at least @c major.minor.
 166
 167         @see GetOSMajorVersion(), GetOSMinorVersion(),
 168              CheckToolkitVersion()
 169     */
 170     bool CheckOSVersion(int major, int minor) const;
 171
 172     /**
 173         Returns @true if the toolkit version is at least @c major.minor.
 174
 175         @see GetToolkitMajorVersion(),
 176              GetToolkitMinorVersion(), CheckOSVersion()
 177     */
 178     bool CheckToolkitVersion(int major, int minor) const;
 179
 180     /**
 181         Returns the global wxPlatformInfo object, initialized with the values
 182         for the currently running platform.
 183     */
 184     static const wxPlatformInfo Get();
 185
 186     /**
 187         Converts the given string to a wxArchitecture enum value or to
 188         @c wxARCH_INVALID if the given string is not a valid architecture string
 189         (i.e. does not contain nor @c 32 nor @c 64 strings).
 190     */
 191     static wxArchitecture GetArch(const wxString& arch);
 192
 193     /**
 194         Returns the name for the given wxArchitecture enumeration value.
 195     */
 196     static wxString GetArchName(wxArchitecture arch) const;
 197
 198     /**
 199         Returns the name for the architecture of this wxPlatformInfo instance.
 200     */
 201     wxString GetArchName() const;
 202
 203     /**
 204         Returns the architecture ID of this wxPlatformInfo instance.
 205     */
 206     wxArchitecture GetArchitecture() const;
 207
 208     /**
 209         Converts the given string to a wxEndianness enum value or to
 210         @c wxENDIAN_INVALID if the given string is not a valid endianness
 211         string (i.e. does not contain nor little nor big strings).
 212     */
 213     static wxEndianness GetEndianness(const wxString& end) const;
 214
 215     /**
 216         Returns the endianness ID of this wxPlatformInfo instance.
 217     */
 218     wxEndianness GetEndianness() const;
 219
 220     /**
 221         Returns name for the given wxEndianness enumeration value.
 222     */
 223     static wxString GetEndiannessName(wxEndianness end) const;
 224
 225     /**
 226         Returns the name for the endianness of this wxPlatformInfo instance.
 227     */
 228     wxString GetEndiannessName() const;
 229
 230     /**
 231         Returns the run-time major version of the OS associated with this
 232         wxPlatformInfo instance.
 233
 234         @see ::wxGetOsVersion(), CheckOSVersion()
 235     */
 236     int GetOSMajorVersion() const;
 237
 238     /**
 239         Returns the run-time minor version of the OS associated with this
 240         wxPlatformInfo instance.
 241
 242         @see ::wxGetOsVersion(), CheckOSVersion()
 243     */
 244     int GetOSMinorVersion() const;
 245
 246     /**
 247         Returns the operating system family name for the given wxOperatingSystemId
 248         enumeration value: @c Unix for @c wxOS_UNIX, @c Macintosh for @c wxOS_MAC,
 249         @c Windows for @c wxOS_WINDOWS, @c DOS for @c wxOS_DOS, @c OS/2 for @c wxOS_OS2.
 250     */
 251     static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const;
 252
 253     /**
 254         Returns the operating system family name of the OS associated with this
 255         wxPlatformInfo instance.
 256     */
 257     wxString GetOperatingSystemFamilyName() const;
 258
 259     /**
 260         Converts the given string to a wxOperatingSystemId enum value or to @c
 261         wxOS_UNKNOWN if the given string is not a valid operating system name.
 262     */
 263     static wxOperatingSystemId GetOperatingSystemId(const wxString& name) const;
 264
 265     /**
 266         Returns the operating system ID of this wxPlatformInfo instance.
 267     */
 268     wxOperatingSystemId GetOperatingSystemId() const;
 269
 270     /**
 271         Returns the name for the given operating system ID value.
 272
 273         This can be a long name (e.g. <tt>Microsoft Windows NT</tt>);
 274         use GetOperatingSystemFamilyName() to retrieve a short, generic name.
 275     */
 276     static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const;
 277
 278     /**
 279         Returns the operating system name of the OS associated with this wxPlatformInfo
 280         instance.
 281     */
 282     wxString GetOperatingSystemIdName() const;
 283
 284
 285     /**
 286         Converts the given string to a wxWidgets port ID value or to @c wxPORT_UNKNOWN
 287         if the given string does not match any of the wxWidgets canonical name ports
 288         ("wxGTK", "wxMSW", etc) nor any of the short wxWidgets name ports ("gtk", "msw", etc).
 289     */
 290     static wxPortId GetPortId(const wxString& portname) const;
 291
 292     /**
 293         Returns the wxWidgets port ID associated with this wxPlatformInfo instance.
 294     */
 295     wxPortId GetPortId() const;
 296
 297     /**
 298         Returns the name of the given wxWidgets port ID value.
 299         The @a usingUniversal argument specifies whether the port is in its native
 300         or wxUniversal variant.
 301
 302         The returned string always starts with the "wx" prefix and is a mixed-case string.
 303     */
 304     static wxString GetPortIdName(wxPortId port, bool usingUniversal) const;
 305
 306     /**
 307         Returns the name of the wxWidgets port ID associated with this wxPlatformInfo
 308         instance.
 309     */
 310     wxString GetPortIdName() const;
 311
 312     /**
 313         Returns the short name of the given wxWidgets port ID value.
 314         The @a usingUniversal argument specifies whether the port is in its native
 315         or wxUniversal variant.
 316
 317         The returned string does not start with the "wx" prefix and is always lower
 318         case.
 319     */
 320     static wxString GetPortIdShortName(wxPortId port,
 321                                        bool usingUniversal) const;
 322
 323     /**
 324         Returns the short name of the wxWidgets port ID associated with this
 325         wxPlatformInfo instance.
 326     */
 327     wxString GetPortIdShortName() const;
 328
 329     /**
 330         Returns the run-time major version of the toolkit associated with this
 331         wxPlatformInfo instance.
 332
 333         Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero
 334         (unless externally modified with SetToolkitVersion()); that is, no native
 335         toolkit is in use.
 336         See wxAppTraits::GetToolkitVersion() for more info.
 337
 338         @see CheckToolkitVersion()
 339     */
 340     int GetToolkitMajorVersion() const;
 341
 342     /**
 343         Returns the run-time minor version of the toolkit associated with this
 344         wxPlatformInfo instance.
 345
 346         Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero
 347         (unless externally modified with SetToolkitVersion()); that is, no native
 348         toolkit is in use.
 349         See wxAppTraits::GetToolkitVersion() for more info.
 350
 351         @see CheckToolkitVersion()
 352     */
 353     int GetToolkitMinorVersion() const;
 354
 355     /**
 356         Returns @true if this instance is fully initialized with valid values.
 357     */
 358     bool IsOk() const;
 359
 360     /**
 361         Returns @true if this wxPlatformInfo describes wxUniversal build.
 362     */
 363     bool IsUsingUniversalWidgets() const;
 364
 365     /**
 366         Sets the architecture enum value associated with this wxPlatformInfo instance.
 367     */
 368     void SetArchitecture(wxArchitecture n);
 369
 370     /**
 371         Sets the endianness enum value associated with this wxPlatformInfo instance.
 372     */
 373     void SetEndianness(wxEndianness n);
 374
 375     /**
 376         Sets the version of the operating system associated with this wxPlatformInfo
 377         instance.
 378     */
 379     void SetOSVersion(int major, int minor);
 380
 381     /**
 382         Sets the operating system associated with this wxPlatformInfo instance.
 383     */
 384     void SetOperatingSystemId(wxOperatingSystemId n);
 385
 386     /**
 387         Sets the wxWidgets port ID associated with this wxPlatformInfo instance.
 388     */
 389     void SetPortId(wxPortId n);
 390
 391     /**
 392         Sets the version of the toolkit associated with this wxPlatformInfo instance.
 393     */
 394     void SetToolkitVersion(int major, int minor);
 395
 396     /**
 397         Inequality operator. Tests all class' internal variables.
 398     */
 399     bool operator!=(const wxPlatformInfo& t) const;
 400
 401     /**
 402         Equality operator. Tests all class' internal variables.
 403     */
 404     bool operator==(const wxPlatformInfo& t) const;
 405 };
 406