wxDateTime timezone functions now dynamic (no caching).

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

diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h
index d082af4b97976c92eb2366a851f4ec95df2c91bb..8de3c97ae219f1a61a7873fd74dbf186edf69304 100644 (file)
--- a/interface/wx/stdpaths.h
+++ b/interface/wx/stdpaths.h
@@ -19,10 +19,16 @@
     the Windows directory may be named @c "W:\Win2003" instead of
     the default @c "C:\Windows".
 
-    The strings @c appname and @c username should be replaced with the value
-    returned by wxApp::GetAppName() and the name of the currently logged in user,
-    respectively. The string @c prefix is only used under Unix and is @c /usr/local by
-    default but may be changed using wxStandardPaths::SetInstallPrefix.
+    Notice that in the examples below the string @c appname 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().
+
+    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.
+    and @c prefix is only used under Unix and is @c /usr/local by default but
+    may be changed using wxStandardPaths::SetInstallPrefix().
 
     The directories returned by the methods of this class may or may not exist.
     If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
@@ -48,6 +54,19 @@
 class wxStandardPaths
 {
 public:
+    /**
+        MSW-specific function undoing the effect of IgnoreAppSubDir() calls.
+
+        After a call to this function the program directory will be exactly the
+        directory containing the main application binary, i.e. it undoes the
+        effect of any previous IgnoreAppSubDir() calls including the ones done
+        indirectly by IgnoreAppBuildSubDirs() called from the class
+        constructor.
+
+        @since 2.9.1
+     */
+    void DontIgnoreAppSubDir();
+
     /**
         Returns reference to the unique global standard paths object.
     */
@@ -215,6 +234,73 @@ public:
     */
     virtual wxString GetUserLocalDataDir() const;
 
+    /**
+        MSW-specific function to customize application directory detection.
+
+        This class supposes that data, plugins &c files are located under the
+        program directory which is the directory containing the application
+        binary itself. But sometimes this binary may be in a subdirectory of
+        the main program directory, e.g. this happens in at least the following
+        common cases:
+         - The program is in "bin" subdirectory of the installation directory.
+         - The program is in "debug" subdirectory of the directory containing
+           sources and data files during development
+
+        By calling this function you instruct the class to remove the last
+        component of the path if it matches its argument. Notice that it may be
+        called more than once, e.g. you can call both IgnoreAppSubDir("bin") and
+        IgnoreAppSubDir("debug") to take care of both production and development
+        cases above but that each call will only remove the last path component.
+        Finally note that the argument can contain wild cards so you can also
+        call IgnoreAppSubDir("vc*msw*") to ignore all build directories at once
+        when using wxWidgets-inspired output directories names.
+
+        @since 2.9.1
+
+        @see IgnoreAppBuildSubDirs()
+
+        @param subdirPattern
+            The subdirectory containing the application binary which should be
+            ignored when determining the top application directory. The pattern
+            is case-insensitive and may contain wild card characters @c '?' and
+            @c '*'.
+     */
+    void IgnoreAppSubDir(const wxString& subdirPattern);
+
+    /**
+        MSW-specific function to ignore all common build directories.
+
+        This function calls IgnoreAppSubDir() with all common values for build
+        directory, e.g. @c "debug" and @c "release".
+
+        It is called by the class constructor and so the build directories are
+        always ignored by default. You may use DontIgnoreAppSubDir() to avoid
+        ignoring them if this is inappropriate for your application.
+
+        @since 2.9.1
+     */
+    void IgnoreAppBuildSubDirs();
+
+    /**
+        Returns location of Windows shell special folder.
+
+        This function is, by definition, MSW-specific. It can be used to access
+        pre-defined shell directories not covered by the existing methods of
+        this class, e.g.:
+        @code
+        #ifdef __WXMSW__
+            // get the location of files waiting to be burned on a CD
+            wxString cdburnArea =
+                wxStandardPaths::MSWGetShellDir(CSIDL_CDBURN_AREA);
+        #endif // __WXMSW__
+        @endcode
+
+        @param csidl
+
+        @since 2.9.1
+     */
+    static wxString MSWGetShellDir(int csidl);
+
     /**
         Lets wxStandardPaths know about the real program installation prefix on a Unix
         system. By default, the value returned by GetInstallPrefix() is used.
@@ -239,6 +325,8 @@ public:
 
         By default, only the application name is used under Unix systems but both
         application and vendor names are used under Windows and Mac.
+
+        @since 2.9.0
     */
     void UseAppInfo(int info);
 };