45
45
RemovableMedia = 0x00000001, //!< Search on removable media if present (default is not to).
46
46
Writable = 0x00000002, //!< Only return writable paths. For directories this means
47
//!< that it is possible to create files within the directory.
47
//!< that it is possible to create files within the directory.
48
48
Directory = 0x00000004, //!< Exclude non-directories.
49
49
File = 0x00000008, //!< Exclude non-files.
50
50
New = 0x00000010, //!< Exclude existing paths.
51
Hidden = 0x00000020 //!< Include "hidden" paths (starting with a . on POSIX systems).
51
Hidden = 0x00000020 //!< Include "hidden" paths (starting with a . on POSIX systems).
54
//! Initialize the directories.
55
55
//! By default, StelFileMgr will be created with the Stellarium installation directory
56
//! config_root in the search path. On systems which provide a per-user data/settings
57
//! directory (which we call the user_settings directory, this is also included in
56
//! config_root in the search path. On systems which provide a per-user data/settings
57
//! directory (which we call the user_settings directory, this is also included in
58
58
//! the search path, before the \<config_root> directory.
64
61
//! Search for a path within the search paths, for example "textures/fog.png".
65
62
//! findFile looks through the search paths in order, returning the first instance
66
63
//! of the specified path. By specifying a flags parameter it is possible to constrain
67
64
//! the results to those matching various criteria.
68
65
//! If the path argument is a complete path (is a full path on single root OSes, or
69
//! unanbigiously identifies one and only one file on multi-root OSes), it will
66
//! unanbigiously identifies one and only one file on multi-root OSes), it will
70
67
//! be tested for compliance with other conditions - the regular search path will
72
//! If you wish to search for a non-exiting file which is not in the search path
69
//! If you wish to search for a non-exiting file which is not in the search path
73
70
//! you should explicitly prefix it with "./", or otherwise have a . at the start of
74
71
//! the path parameter, e.g. path="./my_config_file_in_the_pwd.ini"
75
72
//! @param path the name of the file to search for, for example "textures/fog.png".
77
74
//! @return returns a full path of the file if found, else return an empty path.
78
75
//! @exception std::runtime_error what() -> "file not found: [filename]"
79
76
//! @exception std::runtime_error what() -> "file does not match flags: [fullpath]".
80
//! This exception occurs if a full path is passes at the path argument, but
77
//! This exception occurs if a full path is passes at the path argument, but
81
78
//! that path does not match the flags specified.
82
QString findFile(const QString& path, const Flags& flags=(Flags)0);
79
static QString findFile(const QString& path, const Flags& flags=(Flags)0);
84
81
//! Set a set of all possible files/directories in any Stellarium search directory
85
82
//! @param path the path to search inside, e.g. "landscapes"
86
83
//! @param flags options which constrain the result
87
84
//! @param recursive if true, all sub-directories are walked recursively
88
//! @return returns a QSet of file and.or directory names, which are available
89
//! in any of the search paths + path. Returns empty set if none were found
85
//! @return returns a QSet of file and.or directory names, which are available
86
//! in any of the search paths + path. Returns empty set if none were found
90
87
//! or the path is invalid (not a directory / not existing).
91
QSet<QString> listContents(const QString& path, const Flags& flags=(Flags)0, bool recursive=false);
88
static QSet<QString> listContents(const QString& path, const Flags& flags=(Flags)0, bool recursive=false);
93
90
//! Get a vector of strings which describes the current search paths.
94
91
//! @return returns a vector of strings representing the current search paths.
95
const QStringList& getSearchPaths(void) { return fileLocations; }
92
static const QStringList& getSearchPaths(void) {return fileLocations;}
97
94
//! Set the search paths.
98
95
//! @param paths is a vector of strings which will become the new search paths
99
void setSearchPaths(const QStringList& paths);
96
static void setSearchPaths(const QStringList& paths);
98
//! Make sure the passed directory path exist and is writable.
99
//! If it doesn't exist creates it. If it's not possible throws an error.
100
static void makeSureDirExistsAndIsWritable(const QString& dirFullPath);
101
102
//! Check if a path exists. Note it might be a file or a directory.
102
103
//! @param path to check
103
104
static bool exists(const QString& path);
106
//! Check if a path is absolute
107
//! @param path to check
108
static bool isAbsolute(const QString& path);
110
//! Check if a path is readable.
111
//! @return true if file at path is readable, false if not or if the
112
//! file does not exist
113
static bool isReadable(const QString& path);
105
115
//! Check if a path is writable
106
116
//! For files, true is returned if the file exists and is writable
107
117
//! or if the file doesn't exist, but it's parent directory does,
110
120
//! have files created in it.
111
121
//! @param path to check
112
122
static bool isWritable(const QString& path);
114
124
//! Check if a path exists and is a directory.
115
125
//! @param path to check
116
126
static bool isDirectory(const QString& path);
118
128
//! Return the size of the file at the path.
119
129
//! @param path to file
120
130
static qint64 size(const QString& path);
122
132
//! Make a directory
123
133
//! @param path the path of the directory to create.
124
134
//! @return true if success, else false
125
135
static bool mkDir(const QString& path);
127
137
//! Convenience function to find the parent directory of a given path
128
138
//! May return relative paths if the parameter is a relative path
129
139
//! @param path the path whose parent directory is to be returned
130
QString dirName(const QString& path);
132
//! Get the user's Desktop directory
140
static QString dirName(const QString& path);
142
//! Convenience function to find the basename of a given path
143
//! May return relative paths if the parameter is a relative path
144
//! @param path the path whose parent directory is to be returned
145
static QString baseName(const QString& path);
147
//! Get the user's Desktop directory.
133
148
//! This is a portable way to retrieve the directory for the user's desktop.
134
149
//! On Linux and OSX this is $HOME/Desktop. For Windows, the system is queried
135
150
//! using SHGetSpecialFolderLocation. If that doesn't work, the USERPROFILE
138
153
//! @return the path to the user's desktop directory
139
154
//! @exception NOT_FOUND when the directory cannot be determined, or the
140
155
//! OS doesn't provide one.
141
QString getDesktopDir(void);
143
//! Returns the path to the user directory
144
//! This is the directory where we expect to find the [default] writable
156
static QString getDesktopDir();
158
//! Returns the path to the user directory.
159
//! This is the directory where we expect to find the [default] writable
145
160
//! configuration file, user versions of scripts, nebulae, stars, skycultures etc.
146
161
//! It will be the first directory in the path which is used when
147
162
//! trying to find most data files
148
//! @return the path to the user private data directory
149
//! @exception NOT_FOUND if the directory could not be found
150
QString getUserDir(void);
163
//! @return the path to the user private data directory
164
//! @exception NOT_FOUND if the directory could not be found
165
static QString getUserDir();
167
//! Returns the path to the installation directory
168
//! This is the directory where we expect to find scripts, nebulae, stars,
169
//! skycultures etc, and will be added at the end of the search path
170
//! @return the path to the installation data directory
171
//! @exception NOT_FOUND if the directory could not be found
172
static QString getInstallationDir();
174
//! Returns the path to the cache directory. Note that subdirectories may need to be created for specific caches.
175
static QString getCacheDir();
152
177
//! Sets the user directory. This updates the search paths (first element)
153
178
//! @param newDir the new value of the user directory
154
179
//! @exception NOT_VALID if the specified user directory is not usable
155
void setUserDir(const QString& newDir);
157
//! This is the directory into which screenshots will be saved
180
static void setUserDir(const QString& newDir);
182
//! This is the directory into which screenshots will be saved.
158
183
//! It is $HOME on Linux, BSD, Solaris etc.
159
184
//! It is the user's Desktop on MacOS X (??? - someone please verify this)
160
185
//! It is ??? on Windows
161
186
//! @return the path to the directory where screenshots are saved
162
//! @exception NOT_FOUND if the directory could not be found
163
QString getScreenshotDir(void);
187
static QString getScreenshotDir();
165
189
//! Sets the screenshot directory.
166
190
//! This is set to platform-specific values in the StelFileMgr constructor,
167
191
//! but it is settable using this function to make it possible to implement
168
192
//! the command-line option which specifies where screenshots go.
169
193
//! @param newDir the new value of the screenshot directory
170
void setScreenshotDir(const QString& newDir);
194
static void setScreenshotDir(const QString& newDir);
172
196
//! get the directory for locate files (i18n)
173
197
//! @return the path to the locale directory or "" if the locale directory could not be found.
174
QString getLocaleDir(void);
198
static QString getLocaleDir();
177
//! Check if the user directory exists, is writable and a directory
178
//! Creates it if it does not exist. Exits the program if any of this
182
//! Convenience function to find the basename of a given path
183
//! May return relative paths if the parameter is a relative path
184
//! @param path the path whose parent directory is to be returned
185
QString baseName(const QString& path);
187
//! Returns the path to the installation directory
188
//! This is the directory where we expect to find scripts, nebulae, stars,
189
//! skycultures etc, and will be added at the end of the search path
190
//! @return the path to the installation data directory
191
//! @exception NOT_FOUND if the directory could not be found
192
QString getInstallationDir(void);
202
//! No one can create an instance.
194
205
//! Check if a (complete) path matches a set of flags
195
206
//! @param path a complete path
196
207
//! @param flags a set of StelFileMgr::Flags to test against path
197
208
//! @return true if path passes all flag tests, else false
199
bool fileFlagsCheck(const QString& path, const Flags& flags=(Flags)0);
201
QStringList fileLocations;
210
static bool fileFlagsCheck(const QString& path, const Flags& flags=(Flags)0);
212
static QStringList fileLocations;
203
214
//! Used to store the user data directory
215
static QString userDir;
206
217
//! Used to store the screenshot directory
207
QString screenshotDir;
218
static QString screenshotDir;
209
220
#if defined(WIN32)
210
221
//! For internal use - retreives windows special named directories.
211
222
//! @param csidlId identifier for directoy, e.g. CSIDL_APPDATA
212
static QString getWin32SpecialDirPath(const int csidlId);
223
static QString getWin32SpecialDirPath(int csidlId);