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     DocDeclStr(
  79         virtual wxString , GetExecutablePath() const,
  80         "Return the path (directory+filename) of the running executable or an
  81 empty string if it couldn't be determined.  The path is returned as an
  82 absolute path whenever possible.", "");
  83
  84
  85     DocDeclStr(
  86         virtual wxString , GetConfigDir() const,
  87         "Return the directory with system config files: /etc under Unix,
  88 'c:\\Documents and Settings\\All Users\\Application Data' under Windows,
  89 /Library/Preferences for Mac", "");
  90
  91
  92     DocDeclStr(
  93         virtual wxString , GetUserConfigDir() const,
  94         "Return the directory for the user config files: $HOME under Unix,
  95 'c:\\Documents and Settings\\username' under Windows, and
  96 ~/Library/Preferences under Mac
  97
  98 Only use this if you have a single file to put there, otherwise
  99 `GetUserDataDir` is more appropriate", "");
 100
 101
 102     DocDeclStr(
 103         virtual wxString , GetDataDir() const,
 104         "Return the location of the application's global, (i.e. not
 105 user-specific,) data files: prefix/share/appname under Unix,
 106 'c:\\Program Files\\appname' under Windows,
 107 appname.app/Contents/SharedSupport app bundle directory under Mac.", "");
 108
 109
 110     DocDeclStr(
 111         virtual wxString , GetLocalDataDir() const,
 112         "Return the location for application data files which are
 113 host-specific.  Same as `GetDataDir` except under Unix where it is
 114 /etc/appname", "");
 115
 116
 117     DocDeclStr(
 118         virtual wxString , GetUserDataDir() const,
 119         "Return the directory for the user-dependent application data files:
 120 $HOME/.appname under Unix, c:\\Documents and
 121 Settings\\username\\Application Data\\appname under Windows and
 122 ~/Library/Application Support/appname under Mac", "");
 123
 124
 125     DocDeclStr(
 126         virtual wxString , GetUserLocalDataDir() const,
 127         "Return the directory for user data files which shouldn't be shared
 128 with the other machines
 129
 130 Same as `GetUserDataDir` for all platforms except Windows where it is
 131 the 'Local Settings\\Application Data\\appname' directory.", "");
 132
 133
 134     DocDeclStr(
 135         virtual wxString , GetPluginsDir() const,
 136         "Return the directory where the loadable modules (plugins) live:
 137 prefix/lib/appname under Unix, program directory under Windows and
 138 Contents/Plugins app bundle subdirectory under Mac", "");
 139
 140
 141     // get resources directory: resources are auxiliary files used by the
 142     // application and include things like image and sound files
 143     //
 144     // same as GetDataDir() for all platforms except Mac where it returns
 145     // Contents/Resources subdirectory of the app bundle
 146     DocDeclStr(
 147         virtual wxString , GetResourcesDir() const,
 148         "Get resources directory.  Resources are auxiliary files used by the
 149 application and include things like image and sound files.
 150
 151 Same as `GetDataDir` for all platforms except Mac where it returns
 152 Contents/Resources subdirectory of the app bundle.", "");
 153
 154
 155     DocDeclStr(
 156         virtual wxString ,
 157         GetLocalizedResourcesDir(const wxString& lang,
 158                                  ResourceCat category = ResourceCat_None) const,
 159         "Get localized resources directory containing the resource files of the
 160 specified category for the given language.
 161
 162 In general this is just GetResourcesDir()/lang under Windows and Unix
 163 and GetResourcesDir()/lang.lproj under Mac but is something quite
 164 different under Unix for the message catalog category (namely the
 165 standard prefix/share/locale/lang/LC_MESSAGES.)", "");
 166
 167     DocDeclStr(
 168         virtual wxString , GetDocumentsDir() const,
 169         "Return the Documents directory for the current user.
 170
 171 C:\Documents and Settings\username\Documents under Windows,
 172 $HOME under Unix and ~/Documents under Mac", "");
 173
 174     DocDeclStr(
 175         virtual wxString , GetTempDir() const,
 176         "Return the user's directory for temporary files.", "");
 177
 178
 179     DocStr(SetInstallPrefix,
 180            "Set the program installation directory which is /usr/local by default.
 181 This value will be used by other methods such as `GetDataDir` and
 182 `GetPluginsDir` as the prefix for what they return. (This function
 183 only has meaning on Unix systems.)", "");
 184
 185     DocStr(GetInstallPrefix,
 186            "Get the program installation prefix. The default is the prefix where
 187 Python is installed. (This function only has meaning on Unix systems.)", "");
 188
 189 #ifdef __WXGTK__
 190     void SetInstallPrefix(const wxString& prefix);
 191     wxString GetInstallPrefix() const;
 192 #else
 193     %extend {
 194         void SetInstallPrefix(const wxString& prefix) {}
 195         wxString GetInstallPrefix() { return wxEmptyString; }
 196     }
 197 #endif
 198 };
 199
 200
 201 //---------------------------------------------------------------------------