StelFileMgr.hpp   StelFileMgr.hpp 
skipping to change at line 47 skipping to change at line 47
//! @author Lippo Huhtala <lippo.huhtala@meridea.com> //! @author Lippo Huhtala <lippo.huhtala@meridea.com>
//! @author Matthew Gates <matthew@porpoisehead.net> //! @author Matthew Gates <matthew@porpoisehead.net>
//! @sa @ref fileStructure description. //! @sa @ref fileStructure description.
class StelFileMgr class StelFileMgr
{ {
public: public:
//! @enum Flags used as named bitfield flags as specifiers to filter results of StelFileMgr methods. //! @enum Flags used as named bitfield flags as specifiers to filter results of StelFileMgr methods.
enum Flags { enum Flags {
RemovableMedia = 0x00000001, //!< Search on removable media if present (default is not to). RemovableMedia = 0x00000001, //!< Search on removable media if present (default is not to).
Writable = 0x00000002, //!< Only return writable path s. For directories this means Writable = 0x00000002, //!< Only return writable path s. For directories this means
//!< that it is possible to cr eate files within the directory. // !< that it is possible to create files within the directory.
Directory = 0x00000004, //!< Exclude non-directories. Directory = 0x00000004, //!< Exclude non-directories.
File = 0x00000008, //!< Exclude non-files. File = 0x00000008, //!< Exclude non-files.
New = 0x00000010, //!< Exclude existing paths. New = 0x00000010, //!< Exclude existing paths.
Hidden = 0x00000020 //!< Include "hidden" paths (st arting with a . on POSIX systems). Hidden = 0x00000020 //!< Include "hidden" paths (st arting with a . on POSIX systems).
}; };
//! Constructor. //! Initialize the directories.
//! By default, StelFileMgr will be created with the Stellarium inst allation directory //! By default, StelFileMgr will be created with the Stellarium inst allation directory
//! config_root in the search path. On systems which provide a per- user data/settings //! config_root in the search path. On systems which provide a per-u ser data/settings
//! directory (which we call the user_settings directory, this is al so included in //! directory (which we call the user_settings directory, this is al so included in
//! the search path, before the \<config_root> directory. //! the search path, before the \<config_root> directory.
StelFileMgr(); static void init();
//! Destructor.
~StelFileMgr();
//! Search for a path within the search paths, for example "textures /fog.png". //! Search for a path within the search paths, for example "textures /fog.png".
//! findFile looks through the search paths in order, returning the first instance //! findFile looks through the search paths in order, returning the first instance
//! of the specified path. By specifying a flags parameter it is po ssible to constrain //! of the specified path. By specifying a flags parameter it is po ssible to constrain
//! the results to those matching various criteria. //! the results to those matching various criteria.
//! If the path argument is a complete path (is a full path on singl e root OSes, or //! If the path argument is a complete path (is a full path on singl e root OSes, or
//! unanbigiously identifies one and only one file on multi-root OSe s), it will //! unanbigiously identifies one and only one file on multi-root OSe s), it will
//! be tested for compliance with other conditions - the regular sea rch path will //! be tested for compliance with other conditions - the regular sea rch path will
//! not be tested. //! not be tested.
//! If you wish to search for a non-exiting file which is not in the search path //! If you wish to search for a non-exiting file which is not in the search path
//! you should explicitly prefix it with "./", or otherwise have a . at the start of //! you should explicitly prefix it with "./", or otherwise have a . at the start of
//! the path parameter, e.g. path="./my_config_file_in_the_pwd.ini" //! the path parameter, e.g. path="./my_config_file_in_the_pwd.ini"
//! @param path the name of the file to search for, for example "tex tures/fog.png". //! @param path the name of the file to search for, for example "tex tures/fog.png".
//! @param flags options which constrain the result. //! @param flags options which constrain the result.
//! @return returns a full path of the file if found, else return an empty path. //! @return returns a full path of the file if found, else return an empty path.
//! @exception std::runtime_error what() -> "file not found: [filena me]" //! @exception std::runtime_error what() -> "file not found: [filena me]"
//! @exception std::runtime_error what() -> "file does not match fla gs: [fullpath]". //! @exception std::runtime_error what() -> "file does not match fla gs: [fullpath]".
//! This exception occurs if a full path is passes at th e path argument, but //! This exception occurs if a full path is passes at th e path argument, but
//! that path does not match the flags specified. //! that path does not match the flags specified.
QString findFile(const QString& path, const Flags& flags=(Flags)0); static QString findFile(const QString& path, const Flags& flags=(Fla gs)0);
//! Set a set of all possible files/directories in any Stellarium se arch directory //! Set a set of all possible files/directories in any Stellarium se arch directory
//! @param path the path to search inside, e.g. "landscapes" //! @param path the path to search inside, e.g. "landscapes"
//! @param flags options which constrain the result //! @param flags options which constrain the result
//! @param recursive if true, all sub-directories are walked recursi vely //! @param recursive if true, all sub-directories are walked recursi vely
//! @return returns a QSet of file and.or directory names, which are available //! @return returns a QSet of file and.or directory names, which are available
//! in any of the search paths + path. Returns empty set if none we re found //! in any of the search paths + path. Returns empty set if none we re found
//! or the path is invalid (not a directory / not existing). //! or the path is invalid (not a directory / not existing).
QSet<QString> listContents(const QString& path, const Flags& flags=( Flags)0, bool recursive=false); static QSet<QString> listContents(const QString& path, const Flags& flags=(Flags)0, bool recursive=false);
//! Get a vector of strings which describes the current search paths . //! Get a vector of strings which describes the current search paths .
//! @return returns a vector of strings representing the current sea rch paths. //! @return returns a vector of strings representing the current sea rch paths.
const QStringList& getSearchPaths(void) { return fileLocations; } static const QStringList& getSearchPaths(void) {return fileLocations ;}
//! Set the search paths. //! Set the search paths.
//! @param paths is a vector of strings which will become the new se arch paths //! @param paths is a vector of strings which will become the new se arch paths
void setSearchPaths(const QStringList& paths); static void setSearchPaths(const QStringList& paths);
//! Make sure the passed directory path exist and is writable.
//! If it doesn't exist creates it. If it's not possible throws an e
rror.
static void makeSureDirExistsAndIsWritable(const QString& dirFullPat
h);
//! Check if a path exists. Note it might be a file or a directory. //! Check if a path exists. Note it might be a file or a directory.
//! @param path to check //! @param path to check
static bool exists(const QString& path); static bool exists(const QString& path);
//! Check if a path is absolute
//! @param path to check
static bool isAbsolute(const QString& path);
//! Check if a path is readable.
//! @return true if file at path is readable, false if not or if the
//! file does not exist
static bool isReadable(const QString& path);
//! Check if a path is writable //! Check if a path is writable
//! For files, true is returned if the file exists and is writable //! For files, true is returned if the file exists and is writable
//! or if the file doesn't exist, but it's parent directory does, //! or if the file doesn't exist, but it's parent directory does,
//! if the file can be created. //! if the file can be created.
//! In the case of directories, return true if the directory can //! In the case of directories, return true if the directory can
//! have files created in it. //! have files created in it.
//! @param path to check //! @param path to check
static bool isWritable(const QString& path); static bool isWritable(const QString& path);
//! Check if a path exists and is a directory. //! Check if a path exists and is a directory.
skipping to change at line 130 skipping to change at line 140
static qint64 size(const QString& path); static qint64 size(const QString& path);
//! Make a directory //! Make a directory
//! @param path the path of the directory to create. //! @param path the path of the directory to create.
//! @return true if success, else false //! @return true if success, else false
static bool mkDir(const QString& path); static bool mkDir(const QString& path);
//! Convenience function to find the parent directory of a given pat h //! Convenience function to find the parent directory of a given pat h
//! May return relative paths if the parameter is a relative path //! May return relative paths if the parameter is a relative path
//! @param path the path whose parent directory is to be returned //! @param path the path whose parent directory is to be returned
QString dirName(const QString& path); static QString dirName(const QString& path);
//! Get the user's Desktop directory //! Convenience function to find the basename of a given path
//! May return relative paths if the parameter is a relative path
//! @param path the path whose parent directory is to be returned
static QString baseName(const QString& path);
//! Get the user's Desktop directory.
//! This is a portable way to retrieve the directory for the user's desktop. //! This is a portable way to retrieve the directory for the user's desktop.
//! On Linux and OSX this is $HOME/Desktop. For Windows, the system is queried //! On Linux and OSX this is $HOME/Desktop. For Windows, the system is queried
//! using SHGetSpecialFolderLocation. If that doesn't work, the USE RPROFILE //! using SHGetSpecialFolderLocation. If that doesn't work, the USE RPROFILE
//! environment variable is checked, and if set, \\Desktop is append ed, else //! environment variable is checked, and if set, \\Desktop is append ed, else
//! C:\\Windows\\Desktop is used. //! C:\\Windows\\Desktop is used.
//! @return the path to the user's desktop directory //! @return the path to the user's desktop directory
//! @exception NOT_FOUND when the directory cannot be determined, or the //! @exception NOT_FOUND when the directory cannot be determined, or the
//! OS doesn't provide one. //! OS doesn't provide one.
QString getDesktopDir(void); static QString getDesktopDir();
//! Returns the path to the user directory //! Returns the path to the user directory.
//! This is the directory where we expect to find the [default] writ able //! This is the directory where we expect to find the [default] writ able
//! configuration file, user versions of scripts, nebulae, stars, sk ycultures etc. //! configuration file, user versions of scripts, nebulae, stars, sk ycultures etc.
//! It will be the first directory in the path which is used when //! It will be the first directory in the path which is used when
//! trying to find most data files //! trying to find most data files
//! @return the path to the user private data directory //! @return the path to the user private data directory
//! @exception NOT_FOUND if the directory could not be found //! @exception NOT_FOUND if the directory could not be found
QString getUserDir(void); static QString getUserDir();
//! Returns the path to the installation directory
//! This is the directory where we expect to find scripts, nebulae,
stars,
//! skycultures etc, and will be added at the end of the search path
//! @return the path to the installation data directory
//! @exception NOT_FOUND if the directory could not be found
static QString getInstallationDir();
//! Returns the path to the cache directory. Note that subdirectorie
s may need to be created for specific caches.
static QString getCacheDir();
//! Sets the user directory. This updates the search paths (first e lement) //! Sets the user directory. This updates the search paths (first e lement)
//! @param newDir the new value of the user directory //! @param newDir the new value of the user directory
//! @exception NOT_VALID if the specified user directory is not usab le //! @exception NOT_VALID if the specified user directory is not usab le
void setUserDir(const QString& newDir); static void setUserDir(const QString& newDir);
//! This is the directory into which screenshots will be saved //! This is the directory into which screenshots will be saved.
//! It is $HOME on Linux, BSD, Solaris etc. //! It is $HOME on Linux, BSD, Solaris etc.
//! It is the user's Desktop on MacOS X (??? - someone please verify this) //! It is the user's Desktop on MacOS X (??? - someone please verify this)
//! It is ??? on Windows //! It is ??? on Windows
//! @return the path to the directory where screenshots are saved //! @return the path to the directory where screenshots are saved
//! @exception NOT_FOUND if the directory could not be found static QString getScreenshotDir();
QString getScreenshotDir(void);
//! Sets the screenshot directory. //! Sets the screenshot directory.
//! This is set to platform-specific values in the StelFileMgr const ructor, //! This is set to platform-specific values in the StelFileMgr const ructor,
//! but it is settable using this function to make it possible to im plement //! but it is settable using this function to make it possible to im plement
//! the command-line option which specifies where screenshots go. //! the command-line option which specifies where screenshots go.
//! @param newDir the new value of the screenshot directory //! @param newDir the new value of the screenshot directory
void setScreenshotDir(const QString& newDir); static void setScreenshotDir(const QString& newDir);
//! get the directory for locate files (i18n) //! get the directory for locate files (i18n)
//! @return the path to the locale directory or "" if the locale dir ectory could not be found. //! @return the path to the locale directory or "" if the locale dir ectory could not be found.
QString getLocaleDir(void); static QString getLocaleDir();
private: private:
//! Check if the user directory exists, is writable and a directory
//! Creates it if it does not exist. Exits the program if any of th
is
//! process fails.
void checkUserDir();
//! Convenience function to find the basename of a given path //! No one can create an instance.
//! May return relative paths if the parameter is a relative path StelFileMgr() {;}
//! @param path the path whose parent directory is to be returned
QString baseName(const QString& path);
//! Returns the path to the installation directory
//! This is the directory where we expect to find scripts, nebulae,
stars,
//! skycultures etc, and will be added at the end of the search path
//! @return the path to the installation data directory
//! @exception NOT_FOUND if the directory could not be found
QString getInstallationDir(void);
//! Check if a (complete) path matches a set of flags //! Check if a (complete) path matches a set of flags
//! @param path a complete path //! @param path a complete path
//! @param flags a set of StelFileMgr::Flags to test against path //! @param flags a set of StelFileMgr::Flags to test against path
//! @return true if path passes all flag tests, else false //! @return true if path passes all flag tests, else false
//! @exception misc //! @exception misc
bool fileFlagsCheck(const QString& path, const Flags& flags=(Flags)0 ); static bool fileFlagsCheck(const QString& path, const Flags& flags=( Flags)0);
QStringList fileLocations; static QStringList fileLocations;
//! Used to store the user data directory //! Used to store the user data directory
QString userDir; static QString userDir;
//! Used to store the screenshot directory //! Used to store the screenshot directory
QString screenshotDir; static QString screenshotDir;
#if defined(WIN32) #ifdef Q_OS_WIN
//! For internal use - retreives windows special named directories. //! For internal use - retreives windows special named directories.
//! @param csidlId identifier for directoy, e.g. CSIDL_APPDATA //! @param csidlId identifier for directoy, e.g. CSIDL_APPDATA
static QString getWin32SpecialDirPath(const int csidlId); static QString getWin32SpecialDirPath(int csidlId);
#endif #endif
}; };
#endif // _STELFILEMGR_HPP_ #endif // _STELFILEMGR_HPP_
 End of changes. 28 change blocks. 
46 lines changed or deleted 59 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/