StelFileMgr.hpp   StelFileMgr.hpp 
skipping to change at line 30 skipping to change at line 30
#ifndef _STELFILEMGR_HPP_ #ifndef _STELFILEMGR_HPP_
#define _STELFILEMGR_HPP_ #define _STELFILEMGR_HPP_
#define CHECK_FILE "data/ssystem.ini" #define CHECK_FILE "data/ssystem.ini"
#include <stdexcept> #include <stdexcept>
#include <QSet> #include <QSet>
#include <QString> #include <QString>
#include <QStringList> #include <QStringList>
class QFileInfo;
//! Provides utilities for locating and handling files. //! Provides utilities for locating and handling files.
//! StelFileMgr provides functions for locating files. It maintains a list of //! StelFileMgr provides functions for locating files. It maintains a list of
//! directories in which to look for files called the search path. Typciall y this //! directories in which to look for files called the search path. Typciall y this
//! includes the Stellarium installation directory, and a per-user settings //! includes the Stellarium installation directory, and a per-user settings
//! directory (on platforms which support it). //! directory (on platforms which support it).
//! The concept is that the StelFileMgr will be asked for a named path, and it //! The concept is that the StelFileMgr will be asked for a named path, and it
//! will try to locate that path within each of the search directories. //! will try to locate that path within each of the search directories.
//! @author Lippo Huhtala <lippo.huhtala@meridea.com> //! @author Lippo Huhtala <lippo.huhtala@meridea.com>
//! @author Matthew Gates <matthewg42@gmail.com> //! @author Matthew Gates <matthewg42@gmail.com>
//! @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 RemovableMedia = 0x00000001, //!< Search on removable media
if present (default is not to). if present (default is not to).
Writable = 0x00000002, //!< Only return writable paths Writable = 0x00000002, //!< Only return writable path
. For directories this means s. For directories this means
//!< that it is possible to cre //
ate 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).
}; };
//! Initialize the directories. //! 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-u ser 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.
static void init(); static void init();
//! 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 //! unambigiously 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 static QString findFile(const QString& path, Flags flags=(Flags)0);
me]"
//! @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
//! that path does not match the flags specified.
static QString findFile(const QString& path, const Flags& flags=(Fla
gs)0);
//! List all paths witihin the search paths that match the argument. //! List all paths within the search paths that match the argument.
//! Similar to findFile(), but unlike it this function doesn't stop //! Similar to findFile(), but unlike it this function doesn't stop
//! at the first instance. Instead, it returns a list of paths to al l //! at the first instance. Instead, it returns a list of paths to al l
//! instances. The list is ordered, starting with the most external path //! instances. The list is ordered, starting with the most external path
//! (the first one in fileLocations). //! (the first one in fileLocations).
static QStringList findFileInAllPaths(const QString& path, const Fla gs& flags=(Flags)0); static QStringList findFileInAllPaths(const QString& path, const Fla gs& flags=(Flags)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).
static 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.
static 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
skipping to change at line 156 skipping to change at line 153
//! @param path the path whose parent directory is to be returned //! @param path the path whose parent directory is to be returned
static QString dirName(const QString& path); static QString dirName(const QString& path);
//! Convenience function to find the basename of a given path //! Convenience function to find the basename of a given path
//! 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
static QString baseName(const QString& path); static QString baseName(const QString& path);
//! Get the user's Desktop directory. //! 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 //! On Linux and OSX this is $HOME/Desktop. For Windows, we rely on
is queried Qt.
//! using SHGetSpecialFolderLocation. If that doesn't work, the USE //! @return the path to the user's desktop directory or empty string
RPROFILE if it can't be found.
//! environment variable is checked, and if set, \\Desktop is append
ed, else
//! C:\\Windows\\Desktop is used.
//! @return the path to the user's desktop directory
//! @exception NOT_FOUND when the directory cannot be determined, or
the
//! OS doesn't provide one.
static QString getDesktopDir(); 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
static QString getUserDir(); static QString getUserDir();
//! Returns the path to the installation directory //! Returns the path to the installation directory.
//! This is the directory where we expect to find scripts, nebulae, stars, //! 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 //! skycultures etc, and will be added at the end of the search path
//! @return the path to the installation data directory //! @return the full path to the installation data directory
//! @exception NOT_FOUND if the directory could not be found
static QString getInstallationDir(); static QString getInstallationDir();
//! Returns the path to the cache directory. Note that subdirectorie s may need to be created for specific caches. //! Returns the path to the cache directory. Note that subdirectorie s may need to be created for specific caches.
static QString getCacheDir(); 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
static void setUserDir(const QString& newDir); static void setUserDir(const QString& newDir);
skipping to change at line 217 skipping to change at line 207
private: private:
//! No one can create an instance. //! No one can create an instance.
StelFileMgr() {;} StelFileMgr() {;}
//! 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
static bool fileFlagsCheck(const QString& path, const Flags& flags=( Flags)0); static bool fileFlagsCheck(const QFileInfo& thePath, const Flags& fl ags=(Flags)0);
static QStringList fileLocations; static QStringList fileLocations;
//! Used to store the user data directory //! Used to store the user data directory
static QString userDir; static QString userDir;
//! Used to store the screenshot directory //! Used to store the screenshot directory
static QString screenshotDir; static QString screenshotDir;
//! Used to store the screenshot directory
static QString installDir;
#ifdef Q_OS_WIN #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(int csidlId); static QString getWin32SpecialDirPath(int csidlId);
#endif #endif
}; };
#endif // _STELFILEMGR_HPP_ #endif // _STELFILEMGR_HPP_
 End of changes. 13 change blocks. 
37 lines changed or deleted 23 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/