wxPython/src/_stdpaths.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _stdpaths.i
   3 // Purpose:     SWIG interface for wxStandardPaths
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     10-Nov-2004
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2004 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17
  18 %{
  19 #include <wx/stdpaths.h>
  20 %}
  21
  22
  23 //---------------------------------------------------------------------------
  24 %newgroup
  25
  26 DocStr(wxStandardPaths,
  27 "wx.StandardPaths returns standard locations in the file system and
  28 should be used by programs to find their data files in a portable way.
  29
  30 In the description of the methods below, the example return values are
  31 given for the Unix, Windows and Mac OS X systems, however please note
  32 that these are just  examples and the actual values may differ. For
  33 example, under Windows the system administrator may change the
  34 standard directories locations, i.e. the Windows directory may be
  35 named W:\Win2003 instead of the default C:\Windows.
  36
  37 The strings appname and username should be replaced with the value
  38 returned by `wx.App.GetAppName` and the name of the currently logged
  39 in user, respectively. The string prefix is only used under Unix and
  40 is /usr/local by default but may be changed using `SetInstallPrefix`.
  41
  42 The directories returned by the methods of this class may or may not
  43 exist. If they don't exist, it's up to the caller to create them,
  44 wx.StandardPaths doesn't do it.
  45
  46 Finally note that these functions only work with standardly packaged
  47 applications. I.e. under Unix you should follow the standard
  48 installation conventions and under Mac you should create your
  49 application bundle according to the Apple guidelines. Again, this
  50 class doesn't help you to do it.", "");
  51
  52 class wxStandardPaths
  53 {
  54 public:
  55     // possible resources categorires
  56     enum ResourceCat
  57     {
  58         // no special category
  59         ResourceCat_None,
  60
  61         // message catalog resources
  62         ResourceCat_Messages,
  63
  64         // end of enum marker
  65         ResourceCat_Max
  66     };
  67
  68     DocStr(
  69         Get,
  70         "Return the global standard paths singleton", "");
  71     %extend {
  72         static wxStandardPaths* Get() {
  73             return (wxStandardPaths*) &wxStandardPaths::Get();
  74         }
  75     }
  76
  77
  78
  79     DocDeclStr(
  80         virtual wxString , GetConfigDir() const,
  81         "Return the directory with system config files: /etc under Unix,
  82 'c:\\Documents and Settings\\All Users\\Application Data' under Windows,
  83 /Library/Preferences for Mac", "");
  84
  85
  86     DocDeclStr(
  87         virtual wxString , GetUserConfigDir() const,
  88         "Return the directory for the user config files: $HOME under Unix,
  89 'c:\\Documents and Settings\\username' under Windows, and
  90 ~/Library/Preferences under Mac
  91
  92 Only use this if you have a single file to put there, otherwise
  93 `GetUserDataDir` is more appropriate", "");
  94
  95
  96     DocDeclStr(
  97         virtual wxString , GetDataDir() const,
  98         "Return the location of the application's global, (i.e. not
  99 user-specific,) data files: prefix/share/appname under Unix,
 100 'c:\\Program Files\\appname' under Windows,
 101 appname.app/Contents/SharedSupport app bundle directory under Mac.", "");
 102
 103
 104     DocDeclStr(
 105         virtual wxString , GetLocalDataDir() const,
 106         "Return the location for application data files which are
 107 host-specific.  Same as `GetDataDir` except under Unix where it is
 108 /etc/appname", "");
 109
 110
 111     DocDeclStr(
 112         virtual wxString , GetUserDataDir() const,
 113         "Return the directory for the user-dependent application data files:
 114 $HOME/.appname under Unix, c:\\Documents and
 115 Settings\\username\\Application Data\\appname under Windows and
 116 ~/Library/Application Support/appname under Mac", "");
 117
 118
 119     DocDeclStr(
 120         virtual wxString , GetUserLocalDataDir() const,
 121         "Return the directory for user data files which shouldn't be shared
 122 with the other machines
 123
 124 Same as `GetUserDataDir` for all platforms except Windows where it is
 125 the 'Local Settings\\Application Data\\appname' directory.", "");
 126
 127
 128     DocDeclStr(
 129         virtual wxString , GetPluginsDir() const,
 130         "Return the directory where the loadable modules (plugins) live:
 131 prefix/lib/appname under Unix, program directory under Windows and
 132 Contents/Plugins app bundle subdirectory under Mac", "");
 133
 134
 135     // get resources directory: resources are auxiliary files used by the
 136     // application and include things like image and sound files
 137     //
 138     // same as GetDataDir() for all platforms except Mac where it returns
 139     // Contents/Resources subdirectory of the app bundle
 140     DocDeclStr(
 141         virtual wxString , GetResourcesDir() const,
 142         "Get resources directory.  Resources are auxiliary files used by the
 143 application and include things like image and sound files.
 144
 145 Same as `GetDataDir` for all platforms except Mac where it returns
 146 Contents/Resources subdirectory of the app bundle.", "");
 147
 148
 149     DocDeclStr(
 150         virtual wxString ,
 151         GetLocalizedResourcesDir(const wxString& lang,
 152                                  ResourceCat category = ResourceCat_None) const,
 153         "Get localized resources directory containing the resource files of the
 154 specified category for the given language.
 155
 156 In general this is just GetResourcesDir()/lang under Windows and Unix
 157 and GetResourcesDir()/lang.lproj under Mac but is something quite
 158 different under Unix for the message catalog category (namely the
 159 standard prefix/share/locale/lang/LC_MESSAGES.)", "");
 160
 161     DocDeclStr(
 162         virtual wxString , GetDocumentsDir() const,
 163         "Return the Documents directory for the current user.
 164
 165 C:\Documents and Settings\username\Documents under Windows,
 166 $HOME under Unix and ~/Documents under Mac", "");
 167
 168
 169
 170     DocStr(SetInstallPrefix,
 171            "Set the program installation directory which is /usr/local by default.
 172 This value will be used by other methods such as `GetDataDir` and
 173 `GetPluginsDir` as the prefix for what they return. (This function
 174 only has meaning on Unix systems.)", "");
 175
 176     DocStr(GetInstallPrefix,
 177            "Get the program installation prefix. The default is the prefix where
 178 Python is installed. (This function only has meaning on Unix systems.)", "");
 179
 180 #ifdef __WXGTK__
 181     void SetInstallPrefix(const wxString& prefix);
 182     wxString GetInstallPrefix() const;
 183 #else
 184     %extend {
 185         void SetInstallPrefix(const wxString& prefix) {}
 186         wxString GetInstallPrefix() { return wxEmptyString; }
 187     }
 188 #endif
 189 };
 190
 191
 192 //---------------------------------------------------------------------------