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

#include <StelFileMgr.hpp>

Public Types
enum	Flags { RemovableMedia = 0x00000001 , Writable = 0x00000002 , Directory = 0x00000004 , File = 0x00000008 , New = 0x00000010 }
	used as named bitfield flags as specifiers to filter results of StelFileMgr methods. More...

Static Public Member Functions
static void	init ()
	Initialize the directories. More...

static QString	findFile (const QString &path, Flags flags=static_cast< Flags >(0))
	Search for a path within the search paths, for example "textures/fog.png". More...

static QStringList	findFileInAllPaths (const QString &path, const Flags &flags=static_cast< Flags >(0))
	List all paths within the search paths that match the argument. More...

static QSet< QString >	listContents (const QString &path, const Flags &flags=static_cast< Flags >(0), bool recursive=false)
	Set a set of all possible files/directories in any Stellarium search directory. More...

static const QStringList &	getSearchPaths (void)
	Get a vector of strings which describes the current search paths. More...

static void	setSearchPaths (const QStringList &paths)
	Set the search paths. More...

static void	makeSureDirExistsAndIsWritable (const QString &dirFullPath)
	Make sure the passed directory path exist and is writable. More...

static bool	exists (const QString &path)
	Check if a path exists. More...

static bool	isAbsolute (const QString &path)
	Check if a path is absolute. More...

static bool	isReadable (const QString &path)
	Check if a path is readable. More...

static bool	isWritable (const QString &path)
	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 its parent directory does, if the file can be created. More...

static bool	isDirectory (const QString &path)
	Check if a path exists and is a directory. More...

static qint64	size (const QString &path)
	Return the size of the file at the path. More...

static bool	mkDir (const QString &path)
	Make a directory. More...

static QString	dirName (const QString &path)
	Convenience function to find the parent directory of a given path May return relative paths if the parameter is a relative path. More...

static QString	baseName (const QString &path)
	Convenience function to find the basename of a given path May return relative paths if the parameter is a relative path. More...

static QString	getDesktopDir ()
	Get the user's Desktop directory. More...

static QString	getUserDir ()
	Returns the path to the user directory. More...

static QString	getInstallationDir ()
	Returns the path to the installation directory. More...

static QString	getCacheDir ()
	Returns the path to the cache directory. Note that subdirectories may need to be created for specific caches.

static void	setUserDir (const QString &newDir)
	Sets the user directory. More...

static QString	getScreenshotDir ()
	This is the directory into which screenshots will be saved. More...

static void	setScreenshotDir (const QString &newDir)
	Sets the screenshot directory. More...

static QString	getObsListDir ()
	This is the directory into which observing lists will be saved. More...

static void	setObsListDir (const QString &newDir)
	Sets the observing lists directory. More...

static QString	getLocaleDir ()
	get the directory for locate files (i18n) More...

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. Typically 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.nosp@m..huh.nosp@m.tala@.nosp@m.meri.nosp@m.dea.c.nosp@m.om; Matthew Gates matth.nosp@m.ewg4.nosp@m.2@gma.nosp@m.il.c.nosp@m.om

See also: File and Directory Structure description.

Member Enumeration Documentation

◆ Flags

enum StelFileMgr::Flags

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.

Member Function Documentation

◆ baseName()

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

◆ dirName()

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

◆ exists()

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

◆ findFile()

static QString StelFileMgr::findFile	(	const QString &	path,
		Flags	flags = `static_cast< 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 unambiguously 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-existing 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.

◆ findFileInAllPaths()

static QStringList StelFileMgr::findFileInAllPaths	(	const QString &	path,
		const Flags &	flags = `static_cast< Flags >(0)`
	)

static

List all paths within the search paths that match the argument.

Similar to findFile(), but unlike it this function doesn't stop at the first instance. Instead, it returns a list of paths to all instances. The list is ordered, starting with the most external path (the first one in fileLocations).

◆ getDesktopDir()

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, we rely on Qt.

Returns: the path to the user's desktop directory or empty string if it can't be found.

◆ getInstallationDir()

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 full path to the installation data directory

◆ getLocaleDir()

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.

◆ getObsListDir()

static QString StelFileMgr::getObsListDir ( )

static

This is the directory into which observing lists 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 observing lists are saved

◆ getScreenshotDir()

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

◆ getSearchPaths()

static const QStringList& StelFileMgr::getSearchPaths ( void )

inlinestatic

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

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

◆ getUserDir()

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

◆ init()

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.

◆ isAbsolute()

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

static

Check if a path is absolute.

Parameters

path to check

◆ isDirectory()

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

static

Check if a path exists and is a directory.

Parameters

path to check

◆ isReadable()

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

◆ isWritable()

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 its 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

◆ listContents()

static QSet<QString> StelFileMgr::listContents	(	const QString &	path,
		const Flags &	flags = `static_cast< 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).

◆ makeSureDirExistsAndIsWritable()

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.

◆ mkDir()

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

◆ setObsListDir()

static void StelFileMgr::setObsListDir ( const QString & newDir )

static

Sets the observing lists 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 observing lists go.

Parameters

newDir the new value of the observing lists directory

◆ setScreenshotDir()

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

◆ setSearchPaths()

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

◆ setUserDir()

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

◆ size()

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

static

Return the size of the file at the path.

Parameters

path to file

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Flags

Member Function Documentation

◆ baseName()

◆ dirName()

◆ exists()

◆ findFile()

◆ findFileInAllPaths()

◆ getDesktopDir()

◆ getInstallationDir()

◆ getLocaleDir()

◆ getObsListDir()

◆ getScreenshotDir()

◆ getSearchPaths()

◆ getUserDir()

◆ init()

◆ isAbsolute()

◆ isDirectory()

◆ isReadable()

◆ isWritable()

◆ listContents()

◆ makeSureDirExistsAndIsWritable()

◆ mkDir()

◆ setObsListDir()

◆ setScreenshotDir()

◆ setSearchPaths()

◆ setUserDir()

◆ size()