synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / stdpaths.h

diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h
index 22a36bdb308bbc8dbd94e593bc004babecf484d2..9cd97ca9175443342fa6ee2cbdebd09bf76e5718 100644 (file)
--- a/interface/wx/stdpaths.h
+++ b/interface/wx/stdpaths.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxStandardPaths
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStandardPaths
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -12,6 +12,13 @@
     wxStandardPaths returns the standard locations in the file system and should be
     used by applications to find their data files in a portable way.
 
     wxStandardPaths returns the standard locations in the file system and should be
     used by applications to find their data files in a portable way.
 

+    Note that you must not create objects of class wxStandardPaths directly,
+    but use the global standard paths object returned by wxStandardPaths::Get()
+    (which can be of a type derived from wxStandardPaths and not of exactly
+    this type) and call the methods you need on it. The object returned by
+    Get() may be customized by overriding wxAppTraits::GetStandardPaths()
+    methods.
+

     In the description of the methods below, the example return values are given
     for the Unix, Windows and Mac OS X systems, however please note that these are
     just the examples and the actual values may differ. For example, under Windows:
     In the description of the methods below, the example return values are given
     for the Unix, Windows and Mac OS X systems, however please note that these are
     just the examples and the actual values may differ. For example, under Windows:


@@ -22,8 +29,8 @@
     Notice that in the examples below the string @c appinfo may be either just
     the application name (as returned by wxApp::GetAppName()) or a combination
     of the vendor name (wxApp::GetVendorName()) and the application name, with
     Notice that in the examples below the string @c appinfo may be either just
     the application name (as returned by wxApp::GetAppName()) or a combination
     of the vendor name (wxApp::GetVendorName()) and the application name, with

-    a path separator between them. By default, the vendor name is used under
-    Windows and OS X but not under other Unix systems, see UseAppInfo().
+    a path separator between them. By default, only the application name is
+    used, use UseAppInfo() to change this.

 
     The other placeholders should be self-explanatory: the string @c username
     should be replaced with the value the name of the currently logged in user.
 
     The other placeholders should be self-explanatory: the string @c username
     should be replaced with the value the name of the currently logged in user.


@@ -42,10 +49,6 @@
     This class is MT-safe: its methods may be called concurrently from different
     threads without additional locking.
 
     This class is MT-safe: its methods may be called concurrently from different
     threads without additional locking.
 

-    Note that you don't allocate an instance of class wxStandardPaths, but retrieve the
-    global standard paths object using @c wxStandardPaths::Get on which you call the
-    desired methods.
-

     @library{wxbase}
     @category{file}
 
     @library{wxbase}
     @category{file}
 


@@ -54,6 +57,17 @@
 class wxStandardPaths
 {
 public:
 class wxStandardPaths
 {
 public:

+    /// Possible values for category parameter of GetLocalizedResourcesDir().
+    enum ResourceCat
+    {
+        /// No special category, this is the default.
+        ResourceCat_None,
+
+        /// Message catalog resources category.
+        ResourceCat_Messages
+    };
+
+

     /**
         MSW-specific function undoing the effect of IgnoreAppSubDir() calls.
 
     /**
         MSW-specific function undoing the effect of IgnoreAppSubDir() calls.
 


@@ -103,11 +117,20 @@ public:
     /**
         Return the location of the applications global, i.e. not user-specific,
         data files.
     /**
         Return the location of the applications global, i.e. not user-specific,
         data files.

+

         Example return values:
         - Unix: @c prefix/share/appinfo
         - Windows: the directory where the executable file is located
         - Mac: @c appinfo.app/Contents/SharedSupport bundle subdirectory
 
         Example return values:
         - Unix: @c prefix/share/appinfo
         - Windows: the directory where the executable file is located
         - Mac: @c appinfo.app/Contents/SharedSupport bundle subdirectory
 

+        Under Unix (only) it is possible to override the default value returned
+        from this function by setting the value of @c WX_APPNAME_DATA_DIR
+        environment variable to the directory to use (where @c APPNAME is the
+        upper-cased value of wxApp::GetAppName()). This is useful in order to
+        be able to run applications using this function without installing them
+        as you can simply set this environment variable to the source directory
+        location to allow the application to find its files there.
+

         @see GetLocalDataDir()
     */
     virtual wxString GetDataDir() const;
         @see GetLocalDataDir()
     */
     virtual wxString GetDataDir() const;


@@ -131,7 +154,7 @@ public:
         Example return values:
         - Unix: @c /usr/local/bin/exename
         - Windows: @c "C:\Programs\AppFolder\exename.exe"
         Example return values:
         - Unix: @c /usr/local/bin/exename
         - Windows: @c "C:\Programs\AppFolder\exename.exe"

-        - Mac: @c /Programs/exename
+        - Mac: @c /Applications/exename.app/Contents/MacOS/exename

     */
     virtual wxString GetExecutablePath() const;
 
     */
     virtual wxString GetExecutablePath() const;
 


@@ -142,7 +165,10 @@ public:
         value, otherwise tries to determine it automatically (Linux only right now)
         and finally returns the default @c /usr/local value if it failed.
 
         value, otherwise tries to determine it automatically (Linux only right now)
         and finally returns the default @c /usr/local value if it failed.
 

-        @note This function is only available under Unix.
+        @note This function is only available under Unix platforms (but not limited
+        to wxGTK mentioned below).
+
+        @onlyfor{wxos2,wxgtk}

     */
     wxString GetInstallPrefix() const;
 
     */
     wxString GetInstallPrefix() const;
 


@@ -165,8 +191,9 @@ public:
 
         @since 2.7.0
     */
 
         @since 2.7.0
     */

-    virtual wxString GetLocalizedResourcesDir(const wxString& lang,
-                                              ResourceCat category) const;
+    virtual wxString
+    GetLocalizedResourcesDir(const wxString& lang,
+                             ResourceCat category = ResourceCat_None) const;

 
     /**
         Return the directory where the loadable modules (plugins) live.
 
     /**
         Return the directory where the loadable modules (plugins) live.


@@ -213,7 +240,8 @@ public:
         - Mac: @c ~/Library/Preferences
 
         Only use this method if you have a single configuration file to put in this
         - Mac: @c ~/Library/Preferences
 
         Only use this method if you have a single configuration file to put in this

-        directory, otherwise GetUserDataDir() is more appropriate.
+        directory, otherwise GetUserDataDir() is more appropriate as the latter
+        adds @c appinfo to the path, unlike this function.

     */
     virtual wxString GetUserConfigDir() const;
 
     */
     virtual wxString GetUserConfigDir() const;
 


@@ -310,7 +338,10 @@ public:
         is set during program configuration if using GNU autotools and so it is enough
         to pass its value defined in @c config.h to this function.
 
         is set during program configuration if using GNU autotools and so it is enough
         to pass its value defined in @c config.h to this function.
 

-        @note This function is only available under Unix.
+        @note This function is only available under Unix platforms (but not limited
+        to wxGTK mentioned below).
+
+        @onlyfor{wxos2,wxgtk}

     */
     void SetInstallPrefix(const wxString& prefix);
 
     */
     void SetInstallPrefix(const wxString& prefix);
 


@@ -327,8 +358,7 @@ public:
             used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName |
             AppInfo_VendorName @endcode
 
             used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName |
             AppInfo_VendorName @endcode
 

-        By default, only the application name is used under Unix systems but both
-        application and vendor names are used under Windows and Mac.
+        By default, only the application name is used.

 
         @since 2.9.0
     */
 
         @since 2.9.0
     */