1
#ifndef STELFILEMGR_HPP
2
#define STELFILEMGR_HPP 1
4
#define CHECK_FILE "data/ssystem.ini"
12
//! Provides utilities for locating and handling files.
13
//! StelFileMgr provides functions for locating files. It maintains a list of
14
//! directories in which to look for files called the search path. Typcially this
15
//! includes the Stellarium installation directory, and a per-user settings
16
//! directory (on platforms which support it).
17
//! The concept is that the StelFileMgr will be asked for a named path, and it
18
//! will try to locate that path within each of the search directories.
19
//! @author Lippo Huhtala <lippo.huhtala@meridea.com>
20
//! @author Matthew Gates <matthew@porpoisehead.net>
24
//! @enum FLAGS used as named bitfield flags as specifiers to filter results of StelFileMgr methods.
26
REMOVABLE_MEDIA = 0x00000001, //!< Search on removable media if present (default is not to).
27
WRITABLE = 0x00000002, //!< Only return writable paths. For directories this means
28
//!< that it is possible to create files within the directory.
29
DIRECTORY = 0x00000004, //!< Exclude non-directories.
30
FILE = 0x00000008, //!< Exclude non-files.
31
NEW = 0x00000010, //!< Exclude existing paths.
32
HIDDEN = 0x00000020 //!< Include "hidden" paths (starting with a . on POSIX systems).
36
//! By default, StelFileMgr will be created with the Stellarium installation directory
37
//! config_root in the search path. On systems which provide a per-user data/settings
38
//! directory (which we call the user_settings directory, this is also included in
39
//! the search path, before the <config_root> directory.
45
//! Search for a path within the search paths, for example "textures/fog.png".
46
//! findFile looks through the search paths in order, returning the first instance
47
//! of the specified path. By specifying a flags parameter it is possible to constrain
48
//! the results to those matching various criteria.
49
//! If the path argument is a complete path (is a full path on single root OSes, or
50
//! unanbigiously identifies one and only one file on multi-root OSes), it will
51
//! be tested for compliance with other conditions - the regular search path will
53
//! If you wish to search for a non-exiting file which is not in the search path
54
//! you should explicitly prefix it with "./", or otherwise have a . at the start of
55
//! the path parameter, e.g. path="./my_config_file_in_the_pwd.ini"
56
//! @param path the name of the file to search for, for example "textures/fog.png".
57
//! @param flags options which constrain the result.
58
//! @return returns a full path of the file if found, else return an empty path.
59
//! @exception std::exception what() -> "file not found: [filename]"
60
//! @exception std::exception what() -> "file does not match flags: [fullpath]".
61
//! This exception occurs if a full path is passes at the path argument, but
62
//! that path does not match the flags specified.
63
QString findFile(const QString& path, const FLAGS& flags=(FLAGS)0);
65
//! Set a set of all possible files/directories in any Stellarium search directory
66
//! @param path the path to search inside, e.g. "landscapes"
67
//! @param flags options which constrain the result
68
//! @return returns a std::set of file and directory names (just the basename,
69
//! not the whole path), which are available in any of the search
70
//! paths + path. Returns empty list if none were found or the path
71
//! is invalid (not a directory / not existing)
72
QSet<QString> listContents(const QString& path, const FLAGS& flags=(FLAGS)0);
74
//! Get a vector of strings which describes the current search paths.
75
//! @return returns a vector of strings representing the current search paths.
76
const QStringList& getSearchPaths(void) { return fileLocations; }
78
//! Set the search paths.
79
//! @param paths is a vector of strings which will become the new search paths
80
void setSearchPaths(const QStringList& paths);
82
//! Check if a path exists. Note it might be a file or a directory.
83
//! @param path to check
84
static bool exists(const QString& path);
86
//! Check if a path is writable
87
//! For files, true is returned if the file exists and is writable
88
//! or if the file doesn't exist, but it's parent directory does,
89
//! if the file can be created.
90
//! In the case of directories, return true if the directory can
91
//! have files created in it.
92
//! @param path to check
93
static bool isWritable(const QString& path);
95
//! Check if a path exists and is a directory.
96
//! @param path to check
97
static bool isDirectory(const QString& path);
100
//! @param path the path of the directory to create.
101
//! @return true if success, else false
102
static bool mkDir(const QString& path);
104
//! Convenience function to find the parent directory of a given path
105
//! May return relative paths if the parameter is a relative path
106
//! @param path the path whose parent directory is to be returned
107
QString dirName(const QString& path);
109
//! Get the user's Desktop directory
110
//! This is a portable way to retrieve the directory for the user's desktop.
111
//! On Linux and OSX this is $HOME/Desktop. For Windows, the system is queried
112
//! using SHGetSpecialFolderLocation. If that doesn't work, the USERPROFILE
113
//! environment variable is checked, and if set, \\Desktop is appended, else
114
//! C:\\Windows\\Desktop is used.
115
//! @return the path to the user's desktop directory
116
//! @exception NOT_FOUND when the directory cannot be determined, or the
117
//! OS doesn't provide one.
118
QString getDesktopDir(void);
120
//! Returns the path to the user directory
121
//! This is the directory where we expect to find the [default] writable
122
//! configuration file, user versions of scripts, nebulae, stars, skycultures etc.
123
//! It will be the first directory in the path which is used when
124
//! trying to find most data files
125
//! @return the path to the user private data directory
126
//! @exceptions NOT_FOUND if the directory could not be found
127
QString getUserDir(void);
129
//! This is the directory into which screenshots will be saved
130
//! It is $HOME on Linux, BSD, Solaris etc.
131
//! It is the user's Desktop on MacOS X (??? - someone please verify this)
132
//! It is ??? on Windows
133
//! @return the path to the directory where screenshots are saved
134
//! @exceptions NOT_FOUND if the directory could not be found
135
QString getScreenshotDir(void);
137
//! get the directory for locate files (i18n)
138
//! @return the path to the locale directory or "" if the locale directory could not be found.
139
QString getLocaleDir(void);
142
//! Check if the user directory exists, is writable and a directory
143
//! Creates it if it does not exist. Exits the program if any of this
147
//! Convenience function to find the basename of a given path
148
//! May return relative paths if the parameter is a relative path
149
//! @param path the path whose parent directory is to be returned
150
QString baseName(const QString& path);
152
//! Returns the path to the installation directory
153
//! This is the directory where we expect to find scripts, nebulae, stars,
154
//! skycultures etc, and will be added at the end of the search path
155
//! @return the path to the installation data directory
156
//! @exceptions NOT_FOUND if the directory could not be found
157
QString getInstallationDir(void);
159
//! Check if a (complete) path matches a set of flags
160
//! @param path a complete path
161
//! @param flags a set of StelFileMgr::FLAGS to test against path
162
//! @return true if path passes all flag tests, else false
164
bool fileFlagsCheck(const QString& path, const FLAGS& flags=(FLAGS)0);
166
//! Used to print info to stdout on the current state of the file paths.
167
void outputFileSearchPaths(void);
169
QStringList fileLocations;
added
removed
src/StelFileMgr.hpp
