Home · All Namespaces · All Classes · Functions · Coding Style · Scripting · Plugins · File Structure

StelFileMgr Class Reference

Provides utilities for locating and handling files. More...

#include <StelFileMgr.hpp>

List of all members.

Public Types

enum  Flags {
  RemovableMedia = 0x00000001, Writable = 0x00000002, Directory = 0x00000004, File = 0x00000008,
  New = 0x00000010, Hidden = 0x00000020
}

Static Public Member Functions

static void init ()
static QString findFile (const QString &path, const Flags &flags=(Flags) 0)
static QSet< QString > listContents (const QString &path, const Flags &flags=(Flags) 0, bool recursive=false)
static const QStringList & getSearchPaths (void)
static void setSearchPaths (const QStringList &paths)
static void makeSureDirExistsAndIsWritable (const QString &dirFullPath)
static bool exists (const QString &path)
static bool isAbsolute (const QString &path)
static bool isReadable (const QString &path)
static bool isWritable (const QString &path)
static bool isDirectory (const QString &path)
static qint64 size (const QString &path)
static bool mkDir (const QString &path)
static QString dirName (const QString &path)
static QString baseName (const QString &path)
static QString getDesktopDir ()
static QString getUserDir ()
static QString getInstallationDir ()
static QString getCacheDir ()
static void setUserDir (const QString &newDir)
static QString getScreenshotDir ()
static void setScreenshotDir (const QString &newDir)
static QString getLocaleDir ()


Detailed Description

Provides utilities for locating and handling files.

StelFileMgr provides functions for locating files. It maintains a list of directories in which to look for files called the search path. Typcially this includes the Stellarium installation directory, and a per-user settings directory (on platforms which support 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.

Author:
Lippo Huhtala <lippo.huhtala@meridea.com>

Matthew Gates <matthew@porpoisehead.net>

See also:
File and Directory Structure description.

Member Enumeration Documentation

used as named bitfield flags as specifiers to filter results of StelFileMgr methods.

Enumerator:
RemovableMedia  Search on removable media if present (default is not to).
Writable  Only return writable paths.

For directories this means that it is possible to create files within the directory.

Directory  Exclude non-directories.
File  Exclude non-files.
New  Exclude existing paths.
Hidden  Include "hidden" paths (starting with a . on POSIX systems).


Member Function Documentation

static void StelFileMgr::init (  )  [static]

Initialize the directories.

By default, StelFileMgr will be created with the Stellarium installation directory config_root in the search path. On systems which provide a per-user data/settings directory (which we call the user_settings directory, this is also included in the search path, before the <config_root> directory.

static QString StelFileMgr::findFile ( const QString &  path,
const Flags flags = (Flags) 0 
) [static]

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 of the specified path. By specifying a flags parameter it is possible to constrain the results to those matching various criteria. If the path argument is a complete path (is a full path on single root OSes, or unanbigiously identifies one and only one file on multi-root OSes), it will be tested for compliance with other conditions - the regular search path will not be tested. 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 the path parameter, e.g. path="./my_config_file_in_the_pwd.ini"

Parameters:
path the name of the file to search for, for example "textures/fog.png".
flags options which constrain the result.
Returns:
returns a full path of the file if found, else return an empty path.
Exceptions:
std::runtime_error what() -> "file not found: [filename]"
std::runtime_error what() -> "file does not match flags: [fullpath]". This exception occurs if a full path is passes at the path argument, but that path does not match the flags specified.

static QSet<QString> StelFileMgr::listContents ( const QString &  path,
const Flags flags = (Flags) 0,
bool  recursive = false 
) [static]

Set a set of all possible files/directories in any Stellarium search directory.

Parameters:
path the path to search inside, e.g. "landscapes"
flags options which constrain the result
recursive if true, all sub-directories are walked recursively
Returns:
returns a QSet of file and.or directory names, which are available in any of the search paths + path. Returns empty set if none were found or the path is invalid (not a directory / not existing).

static const QStringList& StelFileMgr::getSearchPaths ( void   )  [inline, static]

Get a vector of strings which describes the current search paths.

Returns:
returns a vector of strings representing the current search paths.

static void StelFileMgr::setSearchPaths ( const QStringList &  paths  )  [static]

Set the search paths.

Parameters:
paths is a vector of strings which will become the new search paths

static void StelFileMgr::makeSureDirExistsAndIsWritable ( const QString &  dirFullPath  )  [static]

Make sure the passed directory path exist and is writable.

If it doesn't exist creates it. If it's not possible throws an error.

static bool StelFileMgr::exists ( const QString &  path  )  [static]

Check if a path exists.

Note it might be a file or a directory.

Parameters:
path to check

static bool StelFileMgr::isAbsolute ( const QString &  path  )  [static]

Check if a path is absolute.

Parameters:
path to check

static bool StelFileMgr::isReadable ( const QString &  path  )  [static]

Check if a path is readable.

Returns:
true if file at path is readable, false if not or if the file does not exist

static bool StelFileMgr::isWritable ( const QString &  path  )  [static]

Check if a path 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, if the file can be created.

In the case of directories, return true if the directory can have files created in it.

Parameters:
path to check

static bool StelFileMgr::isDirectory ( const QString &  path  )  [static]

Check if a path exists and is a directory.

Parameters:
path to check

static qint64 StelFileMgr::size ( const QString &  path  )  [static]

Return the size of the file at the path.

Parameters:
path to file

static bool StelFileMgr::mkDir ( const QString &  path  )  [static]

Make a directory.

Parameters:
path the path of the directory to create.
Returns:
true if success, else false

static QString StelFileMgr::dirName ( const QString &  path  )  [static]

Convenience function to find the parent directory of a given path May return relative paths if the parameter is a relative path.

Parameters:
path the path whose parent directory is to be returned

static QString StelFileMgr::baseName ( const QString &  path  )  [static]

Convenience function to find the basename of a given path May return relative paths if the parameter is a relative path.

Parameters:
path the path whose parent directory is to be returned

static QString StelFileMgr::getDesktopDir (  )  [static]

Get the user's Desktop directory.

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 using SHGetSpecialFolderLocation. If that doesn't work, the USERPROFILE environment variable is checked, and if set, \Desktop is appended, else C:\Windows\Desktop is used.

Returns:
the path to the user's desktop directory
Exceptions:
NOT_FOUND when the directory cannot be determined, or the OS doesn't provide one.

static QString StelFileMgr::getUserDir (  )  [static]

Returns the path to the user directory.

This is the directory where we expect to find the [default] writable configuration file, user versions of scripts, nebulae, stars, skycultures etc. It will be the first directory in the path which is used when trying to find most data files

Returns:
the path to the user private data directory
Exceptions:
NOT_FOUND if the directory could not be found

static QString StelFileMgr::getInstallationDir (  )  [static]

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.

Returns:
the path to the installation data directory
Exceptions:
NOT_FOUND if the directory could not be found

static QString StelFileMgr::getCacheDir (  )  [static]

Returns the path to the cache directory. Note that subdirectories may need to be created for specific caches.

static void StelFileMgr::setUserDir ( const QString &  newDir  )  [static]

Sets the user directory.

This updates the search paths (first element)

Parameters:
newDir the new value of the user directory
Exceptions:
NOT_VALID if the specified user directory is not usable

static QString StelFileMgr::getScreenshotDir (  )  [static]

This is the directory into which screenshots will be saved.

It is $HOME on Linux, BSD, Solaris etc. It is the user's Desktop on MacOS X (??? - someone please verify this) It is ??? on Windows

Returns:
the path to the directory where screenshots are saved

static void StelFileMgr::setScreenshotDir ( const QString &  newDir  )  [static]

Sets the screenshot directory.

This is set to platform-specific values in the StelFileMgr constructor, but it is settable using this function to make it possible to implement the command-line option which specifies where screenshots go.

Parameters:
newDir the new value of the screenshot directory

static QString StelFileMgr::getLocaleDir (  )  [static]

get the directory for locate files (i18n)

Returns:
the path to the locale directory or "" if the locale directory could not be found.


Generated on Mon Mar 22 09:55:38 2010 for Stellarium by  doxygen 1.5.5