X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..7e04f44c8df9a8571d5304718de9a5617701dbab:/interface/wx/platinfo.h

diff --git a/interface/wx/platinfo.h b/interface/wx/platinfo.h
index 7b6a1821e6..b27a2a6f32 100644
--- a/interface/wx/platinfo.h
+++ b/interface/wx/platinfo.h
@@ -12,7 +12,12 @@
     whose version can be detected at run-time.
 
     The values of the constants are chosen so that they can be combined as flags;
-    this allows to check for operating system families like e.g. wxOS_MAC and wxOS_UNIX.
+    this allows to check for operating system families like e.g. @c wxOS_MAC and @c wxOS_UNIX.
+    
+    Note that you can obtain more detailed informations about the current OS
+    version in use by checking the major and minor version numbers returned
+    by ::wxGetOsVersion() or by wxPlatformInfo::GetOSMajorVersion(), 
+    wxPlatformInfo::GetOSMinorVersion().
 */
 enum wxOperatingSystemId
 {
@@ -20,12 +25,16 @@ enum wxOperatingSystemId
 
     wxOS_MAC_OS         = 1 << 0,     //!< Apple Mac OS 8/9/X with Mac paths
     wxOS_MAC_OSX_DARWIN = 1 << 1,     //!< Apple Mac OS X with Unix paths
+    
+    //! A combination of all @c wxOS_MAC_* values previously listed.
     wxOS_MAC = wxOS_MAC_OS|wxOS_MAC_OSX_DARWIN,
 
     wxOS_WINDOWS_9X     = 1 << 2,     //!< Windows 9x family (95/98/ME)
-    wxOS_WINDOWS_NT     = 1 << 3,     //!< Windows NT family (NT/2000/XP)
+    wxOS_WINDOWS_NT     = 1 << 3,     //!< Windows NT family (NT/2000/XP/Vista/7)
     wxOS_WINDOWS_MICRO  = 1 << 4,     //!< MicroWindows
     wxOS_WINDOWS_CE     = 1 << 5,     //!< Windows CE (Window Mobile)
+    
+    //! A combination of all @c wxOS_WINDOWS_* values previously listed.
     wxOS_WINDOWS = wxOS_WINDOWS_9X       |
                     wxOS_WINDOWS_NT      |
                     wxOS_WINDOWS_MICRO   |
@@ -38,6 +47,8 @@ enum wxOperatingSystemId
     wxOS_UNIX_SOLARIS   = 1 << 10,      //!< SunOS
     wxOS_UNIX_AIX       = 1 << 11,      //!< AIX
     wxOS_UNIX_HPUX      = 1 << 12,      //!< HP/UX
+    
+    //! A combination of all @c wxOS_UNIX_* values previously listed.
     wxOS_UNIX = wxOS_UNIX_LINUX     |
                 wxOS_UNIX_FREEBSD   |
                 wxOS_UNIX_OPENBSD   |
@@ -87,7 +98,7 @@ enum wxArchitecture
     wxARCH_INVALID = -1,        //!< returned on error
 
     wxARCH_32,                  //!< 32 bit
-    wxARCH_64,
+    wxARCH_64,                  //!< 64 bit
 
     wxARCH_MAX
 };
@@ -107,19 +118,50 @@ enum wxEndianness
     wxENDIAN_MAX
 };
 
+/**
+    A structure containing informations about a Linux distribution as returned 
+    by the @c lsb_release utility.
+    
+    See wxGetLinuxDistributionInfo() or wxPlatformInfo::GetLinuxDistributionInfo()
+    for more info.
+*/
+struct wxLinuxDistributionInfo
+{
+    wxString Id;                //!< The id of the distribution; e.g. "Ubuntu"
+    wxString Release;           //!< The version of the distribution; e.g. "9.04"
+    wxString CodeName;          //!< The code name of the distribution; e.g. "jaunty"
+    wxString Description;       //!< The description of the distribution; e.g. "Ubuntu 9.04"
+    
+    bool operator==(const wxLinuxDistributionInfo& ldi) const;
+    bool operator!=(const wxLinuxDistributionInfo& ldi) const;
+};
+
 
 /**
     @class wxPlatformInfo
 
-    This class holds informations about the operating system and the toolkit that
-    the application is running under and some basic architecture info of the machine
-    where it's running.
+    This class holds informations about the operating system, the toolkit and the 
+    basic architecture of the machine where the application is currently running.
+    
+    This class does not only have @e getters for the informations above, it also has
+    @e setters. This allows you to e.g. save the current platform informations in a 
+    data file (maybe in string form) so that when you later load it, you can easily
+    retrieve (see the static getters for string->enum conversion functions) and store
+    inside a wxPlatformInfo instance (using its setters) the signature of the system 
+    which generated it.
+    
+    In general however you only need to use the static Get() function and then
+    access the various informations for the current platform:
+    @code
+        wxLogMessage("This application is running under %s.",
+                     wxPlatformInfo::Get().GetOperatingSystemIdName());
+    @endcode
 
     @library{wxbase}
-    @category{misc}
+    @category{cfg}
 
     @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(),
-         wxAppTraits
+         wxAppTraits, @ref group_funcmacro_networkuseros
 */
 class wxPlatformInfo : public wxObject
 {
@@ -164,154 +206,195 @@ public:
              GetToolkitMinorVersion(), CheckOSVersion()
     */
     bool CheckToolkitVersion(int major, int minor) const;
+    
 
     /**
-        Returns the global wxPlatformInfo object, initialized with the values
-        for the currently running platform.
+        Returns @true if this instance is fully initialized with valid values.
     */
-    static const wxPlatformInfo Get();
+    bool IsOk() const;
 
     /**
-        Converts the given string to a wxArchitecture enum value or to
-        @c wxARCH_INVALID if the given string is not a valid architecture string
-        (i.e. does not contain nor @c 32 nor @c 64 strings).
+        Returns @true if this wxPlatformInfo describes wxUniversal build.
     */
-    static wxArchitecture GetArch(const wxString& arch);
+    bool IsUsingUniversalWidgets() const;
 
     /**
-        Returns the name for the given wxArchitecture enumeration value.
+        Inequality operator. Tests all class' internal variables.
     */
-    static wxString GetArchName(wxArchitecture arch) const;
+    bool operator!=(const wxPlatformInfo& t) const;
 
     /**
-        Returns the name for the architecture of this wxPlatformInfo instance.
+        Equality operator. Tests all class' internal variables.
     */
-    wxString GetArchName() const;
+    bool operator==(const wxPlatformInfo& t) const;
+        
+    /**
+        Returns the global wxPlatformInfo object, initialized with the values
+        for the currently running platform.
+    */
+    static const wxPlatformInfo& Get();
+    
+    /**
+        @name Static enum getters
+        
+        These getters allow for easy string-to-enumeration-value conversion.
+    */
+    //@{
 
     /**
-        Returns the architecture ID of this wxPlatformInfo instance.
+        Converts the given string to a wxArchitecture enum value or to
+        @c wxARCH_INVALID if the given string is not a valid architecture string
+        (i.e. does not contain nor @c 32 nor @c 64 strings).
     */
-    wxArchitecture GetArchitecture() const;
+    static wxArchitecture GetArch(const wxString& arch);
 
     /**
         Converts the given string to a wxEndianness enum value or to
         @c wxENDIAN_INVALID if the given string is not a valid endianness
         string (i.e. does not contain nor little nor big strings).
     */
-    static wxEndianness GetEndianness(const wxString& end) const;
+    static wxEndianness GetEndianness(const wxString& end);
 
     /**
-        Returns the endianness ID of this wxPlatformInfo instance.
+        Converts the given string to a wxOperatingSystemId enum value or to @c
+        wxOS_UNKNOWN if the given string is not a valid operating system name.
     */
-    wxEndianness GetEndianness() const;
+    static wxOperatingSystemId GetOperatingSystemId(const wxString& name);
 
     /**
-        Returns name for the given wxEndianness enumeration value.
+        Converts the given string to a wxWidgets port ID value or to @c wxPORT_UNKNOWN
+        if the given string does not match any of the wxWidgets canonical name ports
+        ("wxGTK", "wxMSW", etc) nor any of the short wxWidgets name ports ("gtk", "msw", etc).
     */
-    static wxString GetEndiannessName(wxEndianness end) const;
-
+    static wxPortId GetPortId(const wxString& portname);
+    
+    //@}
+    
+    
     /**
-        Returns the name for the endianness of this wxPlatformInfo instance.
+        @name Static string-form getters
+        
+        These getters allow for easy enumeration-value-to-string conversion.
     */
-    wxString GetEndiannessName() const;
+    //@{
 
     /**
-        Returns the run-time major version of the OS associated with this
-        wxPlatformInfo instance.
-
-        @see ::wxGetOsVersion(), CheckOSVersion()
+        Returns the name for the given wxArchitecture enumeration value.
     */
-    int GetOSMajorVersion() const;
+    static wxString GetArchName(wxArchitecture arch);
 
     /**
-        Returns the run-time minor version of the OS associated with this
-        wxPlatformInfo instance.
-
-        @see ::wxGetOsVersion(), CheckOSVersion()
+        Returns name for the given wxEndianness enumeration value.
     */
-    int GetOSMinorVersion() const;
-
+    static wxString GetEndiannessName(wxEndianness end);
+    
     /**
         Returns the operating system family name for the given wxOperatingSystemId
         enumeration value: @c Unix for @c wxOS_UNIX, @c Macintosh for @c wxOS_MAC,
         @c Windows for @c wxOS_WINDOWS, @c DOS for @c wxOS_DOS, @c OS/2 for @c wxOS_OS2.
     */
-    static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const;
+    static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os);
 
     /**
-        Returns the operating system family name of the OS associated with this
-        wxPlatformInfo instance.
-    */
-    wxString GetOperatingSystemFamilyName() const;
+        Returns the name for the given operating system ID value.
 
-    /**
-        Converts the given string to a wxOperatingSystemId enum value or to @c
-        wxOS_UNKNOWN if the given string is not a valid operating system name.
+        This can be a long name (e.g. <tt>Microsoft Windows NT</tt>);
+        use GetOperatingSystemFamilyName() to retrieve a short, generic name.
     */
-    static wxOperatingSystemId GetOperatingSystemId(const wxString& name) const;
+    static wxString GetOperatingSystemIdName(wxOperatingSystemId os);
 
     /**
-        Returns the operating system ID of this wxPlatformInfo instance.
+        Returns the name of the given wxWidgets port ID value.
+        The @a usingUniversal argument specifies whether the port is in its native
+        or wxUniversal variant.
+
+        The returned string always starts with the "wx" prefix and is a mixed-case string.
     */
-    wxOperatingSystemId GetOperatingSystemId() const;
+    static wxString GetPortIdName(wxPortId port, bool usingUniversal);
 
     /**
-        Returns the name for the given operating system ID value.
+        Returns the short name of the given wxWidgets port ID value.
+        The @a usingUniversal argument specifies whether the port is in its native
+        or wxUniversal variant.
 
-        This can be a long name (e.g. <tt>Microsoft Windows NT</tt>);
-        use GetOperatingSystemFamilyName() to retrieve a short, generic name.
+        The returned string does not start with the "wx" prefix and is always lower case.
     */
-    static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const;
+    static wxString GetPortIdShortName(wxPortId port,
+                                       bool usingUniversal);
 
     /**
-        Returns the operating system name of the OS associated with this wxPlatformInfo
-        instance.
+        Returns the operating system directory.
+        
+        See wxGetOSDirectory() for more info.
     */
-    wxString GetOperatingSystemIdName() const;
+    static wxString GetOperatingSystemDirectory();
 
+    //@}
+    
+    
+    /**
+        @name Getters
+    */
+    //@{
 
     /**
-        Converts the given string to a wxWidgets port ID value or to @c wxPORT_UNKNOWN
-        if the given string does not match any of the wxWidgets canonical name ports
-        ("wxGTK", "wxMSW", etc) nor any of the short wxWidgets name ports ("gtk", "msw", etc).
+        Returns the architecture ID of this wxPlatformInfo instance.
     */
-    static wxPortId GetPortId(const wxString& portname) const;
+    wxArchitecture GetArchitecture() const;
 
     /**
-        Returns the wxWidgets port ID associated with this wxPlatformInfo instance.
+        Returns the endianness ID of this wxPlatformInfo instance.
     */
-    wxPortId GetPortId() const;
+    wxEndianness GetEndianness() const;
 
     /**
-        Returns the name of the given wxWidgets port ID value.
-        The @a usingUniversal argument specifies whether the port is in its native
-        or wxUniversal variant.
+        Returns the run-time major version of the OS associated with this
+        wxPlatformInfo instance.
 
-        The returned string always starts with the "wx" prefix and is a mixed-case string.
+        @see ::wxGetOsVersion(), CheckOSVersion()
     */
-    static wxString GetPortIdName(wxPortId port, bool usingUniversal) const;
+    int GetOSMajorVersion() const;
 
     /**
-        Returns the name of the wxWidgets port ID associated with this wxPlatformInfo
-        instance.
+        Returns the run-time minor version of the OS associated with this
+        wxPlatformInfo instance.
+
+        @see ::wxGetOsVersion(), CheckOSVersion()
     */
-    wxString GetPortIdName() const;
+    int GetOSMinorVersion() const;
 
     /**
-        Returns the short name of the given wxWidgets port ID value.
-        The @a usingUniversal argument specifies whether the port is in its native
-        or wxUniversal variant.
-
-        The returned string does not start with the "wx" prefix and is always lower case.
+        Returns the operating system ID of this wxPlatformInfo instance.
+        
+        See wxGetOsVersion() for more info.
     */
-    static wxString GetPortIdShortName(wxPortId port,
-                                       bool usingUniversal) const;
+    wxOperatingSystemId GetOperatingSystemId() const;
+    
+    /**
+        Returns the description of the operating system of this wxPlatformInfo instance.
+        
+        See wxGetOSDescription() for more info.
+    */
+    wxString GetOperatingSystemDescription() const;
 
     /**
-        Returns the short name of the wxWidgets port ID associated with this
-        wxPlatformInfo instance.
+        Returns the wxWidgets port ID associated with this wxPlatformInfo instance.
     */
-    wxString GetPortIdShortName() const;
+    wxPortId GetPortId() const;
+    
+    /**
+        Returns the Linux distribution info associated with this wxPlatformInfo instance.
+        
+        See wxGetLinuxDistributionInfo() for more info.
+    */
+    wxLinuxDistributionInfo GetLinuxDistributionInfo() const;
+    
+    /**
+        Returns the desktop environment associated with this wxPlatformInfo instance.
+        
+        See wxAppTraits::GetDesktopEnvironment() for more info.
+    */
+    wxString GetDesktopEnvironment() const;
 
     /**
         Returns the run-time major version of the toolkit associated with this
@@ -338,17 +421,58 @@ public:
         @see CheckToolkitVersion()
     */
     int GetToolkitMinorVersion() const;
+    
+    //@}
+
 
     /**
-        Returns @true if this instance is fully initialized with valid values.
+        @name String-form getters
     */
-    bool IsOk() const;
+    //@{
 
     /**
-        Returns @true if this wxPlatformInfo describes wxUniversal build.
+        Returns the name for the architecture of this wxPlatformInfo instance.
     */
-    bool IsUsingUniversalWidgets() const;
+    wxString GetArchName() const;
+
+    /**
+        Returns the name for the endianness of this wxPlatformInfo instance.
+    */
+    wxString GetEndiannessName() const;
+
+    /**
+        Returns the operating system family name of the OS associated with this
+        wxPlatformInfo instance.
+    */
+    wxString GetOperatingSystemFamilyName() const;
+    
+    /**
+        Returns the operating system name of the OS associated with this wxPlatformInfo
+        instance.
+    */
+    wxString GetOperatingSystemIdName() const;
+
+    /**
+        Returns the name of the wxWidgets port ID associated with this wxPlatformInfo
+        instance.
+    */
+    wxString GetPortIdName() const;
+
+    /**
+        Returns the short name of the wxWidgets port ID associated with this
+        wxPlatformInfo instance.
+    */
+    wxString GetPortIdShortName() const;
+    
+    //@}
+    
 
+    
+    /**
+        @name Setters
+    */
+    //@{
+    
     /**
         Sets the architecture enum value associated with this wxPlatformInfo instance.
     */
@@ -381,13 +505,20 @@ public:
     void SetToolkitVersion(int major, int minor);
 
     /**
-        Inequality operator. Tests all class' internal variables.
+        Sets the operating system description associated with this wxPlatformInfo instance.
     */
-    bool operator!=(const wxPlatformInfo& t) const;
-
+    void SetOperatingSystemDescription(const wxString& desc);
+ 
     /**
-        Equality operator. Tests all class' internal variables.
+        Sets the desktop environment associated with this wxPlatformInfo instance.
     */
-    bool operator==(const wxPlatformInfo& t) const;
+    void SetDesktopEnvironment(const wxString& de);
+    
+    /**
+        Sets the linux distribution info associated with this wxPlatformInfo instance.
+    */
+    void SetLinuxDistributionInfo(const wxLinuxDistributionInfo& di);
+    
+    //@}
 };