Utility class for loading a file from a set of locations. More...

#include "resourceloader.h"

Inheritance diagram for LC::Util::ResourceLoader:

Collaboration diagram for LC::Util::ResourceLoader:

Signals
void	watchedDirectoriesChanged ()

Public Member Functions
	ResourceLoader (const QString &relPath, QObject *obj=nullptr)
	Initializes the loader with the given path. More...

void	AddGlobalPrefix ()
	Registers global OS-dependent prefixes. More...

void	AddLocalPrefix (QString prefix=QString())
	Registers a local search prefix. More...

void	SetCacheParams (int size, int timeout)
	Sets the caching parameters of this loader. More...

void	FlushCache ()
	Forcefully flushes the cache. More...

QFileInfoList	List (const QString &option, const QStringList &names={}, QDir::Filters filters=QDir::NoFilter) const
	Lists the available files for the given option. More...

QString	GetPath (const QStringList &pathVariants) const
	Returns the first found path for the list of variants. More...

QString	GetIconPath (const QString &basename) const
	Calls GetPath() with standard variants for the icon extensions. More...

QIODevice_ptr	Load (const QStringList &pathVariants, bool open=false) const
	Returns the QIODevice for the corresponding resource. More...

QIODevice_ptr	Load (const QString &pathVariant, bool open=false) const
	Returns the QIODevice for the corresponding resource. More...

QIODevice_ptr	GetIconDevice (const QString &basename, bool open=false) const
	Returns the QIODevice for the corresponding icon. More...

QPixmap	LoadPixmap (const QString &basename) const
	Returns the pixmap for the given basename. More...

QAbstractItemModel *	GetSubElemModel () const
	Returns the subelement model with the contents of registered paths. More...

void	SetAttrFilters (QDir::Filters)
	Sets the attribute filters for the subelement model. More...

void	SetNameFilters (const QStringList &)
	Sets the name filters for the subelement model. More...

void	SetVerbose (bool verbose)
	Control whether the ResourceLoader prints what it is doing to the logs. More...

Detailed Description

Utility class for loading a file from a set of locations.

One may want to load a resource file from a set of locations, trying them in order and sticking with the first found file. There may be different sets of resources (icon packs, theme packs, etc.) with the same layout of files in them, and one may want to easily load a file from the currently selected set. For example, a theme file may be first searched for in user's home directory, then in some global place, and maybe even somewhere else as well.

This class provides means to make this task easy. The constructor takes a relative path from each location that should be looked for. AddGlobalPrefix() function registers platform-specific search paths (like ones in /usr/share on UNIX and relative to main application binary on Windows). AddLocalPrefix() registers paths relatively to the ~/.leechcraft/data/ path. Then GetPath() function is used to get a full path to the corresponding object or Load() for loading that object. Prefixes are searched for in reverse order, from last registered to first one.

A model suitable for using in XmlSettingsDialog is also provided, which watches for different subdirectories in registered paths and is handy for supporting different sets of resources.

The class also supports filtering its results, filters may be set with SetAttrFilters() and SetNameFilters().

All registered paths are watched for changes, so, for example, installation of new icon packs would require no actions from both user (to make LeechCraft fetch newly installed data) and programmer (to support this feature).

Note: One should make sure that all created instances of this class are deleted in IInfo::Release() or earlier, otherwise deadlocks in directory watcher may prevent LeechCrat from shutting down completely.

Definition at line 69 of file resourceloader.h.

Constructor & Destructor Documentation

◆ ResourceLoader()

LC::Util::ResourceLoader::ResourceLoader	(	const QString &	relPath,
		QObject *	obj = `nullptr`
	)

explicit

Initializes the loader with the given path.

Parameters

[in]	relPath	Path relative to registered prefixes where the resources will be searched for.
[in]	obj	Parent object.

Definition at line 28 of file resourceloader.cpp.

References FlushCache().

Here is the call graph for this function:

Member Function Documentation

◆ AddGlobalPrefix()

void LC::Util::ResourceLoader::AddGlobalPrefix ( )

Registers global OS-dependent prefixes.

Registers global prefixes as search pathes. It's /usr/local/share/leechcraft/ and /usr/share/leechcraft/ on UNIX, share/ in the directory with the main executable on Windows and ../Resources/ dir relative to application path.

Definition at line 84 of file resourceloader.cpp.

◆ AddLocalPrefix()

void LC::Util::ResourceLoader::AddLocalPrefix ( QString prefix = QString () )

Registers a local search prefix.

The prefix string is relative to ~/.leechcraft/data. It may have several directories in the path, like "plugin/directory/subdir".

Definition at line 56 of file resourceloader.cpp.

◆ FlushCache()

void LC::Util::ResourceLoader::FlushCache ( )

Forcefully flushes the cache.

This function may be used to flush the contents of this resource loader cache. It may be useful, for example, when the resources have been updated on disk, and the new versions should be updated right now.

Definition at line 142 of file resourceloader.cpp.

Referenced by ResourceLoader().

Here is the caller graph for this function:

◆ GetIconDevice()

QIODevice_ptr LC::Util::ResourceLoader::GetIconDevice	(	const QString &	basename,
		bool	open = `false`
	)		const

Returns the QIODevice for the corresponding icon.

This function is analogous to GetIconPath().

Parameters

[in]	basename	Base name of the icon — without extension.
[in]	open	Whether the returned QIODevice should be opened automatically.

Returns: The QIODevice for the found path, or a null ptr if nothing is found.

See also: GetIconPath(), LoadPixmap()

Definition at line 265 of file resourceloader.cpp.

◆ GetIconPath()

QString LC::Util::ResourceLoader::GetIconPath ( const QString & basename ) const

Calls GetPath() with standard variants for the icon extensions.

This functions just calls the GetPath() function with standard icon extensions, that is, the path variants are basename + (".svg", ".png", ".jpg")

Note: If possible, consider using GetIconDevice() or LoadPixmap() functions and enabling the cache. That may speed things up considerably.

Parameters

[in] basename Base name of the icon — without extension.

Returns: The first found full path or null string

See also: GetPath(), GetIconDevice()

Definition at line 208 of file resourceloader.cpp.

References GetPath().

Here is the call graph for this function:

◆ GetPath()

QString LC::Util::ResourceLoader::GetPath ( const QStringList & pathVariants ) const

Returns the first found path for the list of variants.

For each registered prefix this function iterates over pathVariants list and checks if the file at $prefix/$relPath/$pathVariant exists, and if it does, the full path to this file is returned. Here, relPath is the path passed to the constructor.

pathVariants may be useful if there may be several representations of each resource. For example, an icon can be in jpg, png or svg format, thus pathVariants would contain something like:

themename/iconname.svg
themename/iconname.png
themename/iconname.jpg Here again, path variants are tried from first to last.

If nothing is found, a null string is returned.

Parameters

[in] pathVariants The list of variants to try.

Returns: The first found full path or null string.

See also: Load(), GetIconPath()

Definition at line 171 of file resourceloader.cpp.

Referenced by GetIconPath().

Here is the caller graph for this function:

◆ GetSubElemModel()

QAbstractItemModel * LC::Util::ResourceLoader::GetSubElemModel ( ) const

Returns the subelement model with the contents of registered paths.

For each prefix in the list of registered prefixes, the contents of $prefix/$relPath are listed in this model, where relPath is the path passed to the constructor. The results are filtered according to the filters set with SetAttrFilters() and SetNameFilters().

This model may be used in settings dialogs as a data source, which may be handy when one wants to implement support for iconsets, theme packs and such things in his plugin.

Returns: The model listing the subelements of registered paths.

See also: SetAttrFilters(), SetNameFilters().

Definition at line 287 of file resourceloader.cpp.

◆ List()

QFileInfoList LC::Util::ResourceLoader::List	(	const QString &	option,
		const QStringList &	names = `{}`,
		QDir::Filters	filters = `QDir::NoFilter`
	)		const

Lists the available files for the given option.

The option should be the one of the elements of the model returned by GetSubElemModel().

This method supports basic filtering: list of name filters could be passed via the names parameter, and additional filter flags via the filters parameter. The default is to perform no additional filtering.

Parameters

[in]	option	The option for which to list available files/directories.
[in]	names	Name filters.
[in]	filters	Additional filters.

Definition at line 148 of file resourceloader.cpp.

◆ Load() [1/2]

QIODevice_ptr LC::Util::ResourceLoader::Load	(	const QString &	pathVariant,
		bool	open = `false`
	)		const

Returns the QIODevice for the corresponding resource.

This function is the overloaded variant of Load(), provided for convenience. This function constructs a stringlist of a single element, the passed pathVariant, and calls the other Load() with it.

Parameters

[in]	pathVariant	The path variant to try.
[in]	open	Whether the returned QIODevice should be opened automatically.

Returns: The QIODevice for the found path, or a null ptr if nothing is found.

Definition at line 260 of file resourceloader.cpp.

References Load().

Here is the call graph for this function:

◆ Load() [2/2]

QIODevice_ptr LC::Util::ResourceLoader::Load	(	const QStringList &	pathVariants,
		bool	open = `false`
	)		const

Returns the QIODevice for the corresponding resource.

This function behaves exactly like GetPath(), except it creates a QIODevice for the found path and opens it.

Parameters

[in]	pathVariants	The list of variants to try.
[in]	open	Whether the returned QIODevice should be opened automatically.

Returns: The QIODevice for the found path, or a null ptr if nothing is found.

Definition at line 213 of file resourceloader.cpp.

Referenced by Load().

Here is the caller graph for this function:

◆ LoadPixmap()

QPixmap LC::Util::ResourceLoader::LoadPixmap ( const QString & basename ) const

Returns the pixmap for the given basename.

This function is analogous to GetIconPath(), but instead of returning the path, it reads the pixmap at that path and returns the pixmap.

If there is no such path, or the pixmap failed to read, a null pixmap is returned.

Parameters

[in] basename Base name of the pixmap — without extension.

Returns: The QPixmap from the found path, or a null pixmap if nothing is found, or if pixmap parsing is failed.

See also: GetIconPath(), GetIconDevice()

Definition at line 270 of file resourceloader.cpp.

◆ SetAttrFilters()

void LC::Util::ResourceLoader::SetAttrFilters ( QDir::Filters filters )

Sets the attribute filters for the subelement model.

This is analogous to QDir's functions for filtering its results.

By default, QDir::Dirs | QDir::NoDotAndDotDot | QDir::Readable is set.

Note: This function should be called before any paths are registered in this resource loader, otherwise unwanted results may occur in the subelement model.

See also: SetNameFilters(), GetSubElemModel()

Definition at line 292 of file resourceloader.cpp.

◆ SetCacheParams()

void LC::Util::ResourceLoader::SetCacheParams	(	int	size,
		int	timeout
	)

Sets the caching parameters of this loader.

This function sets the size of the cache in kibibytes and the timeout between cache flushes in milliseconds. That's it, the cache would be flushed each timeout milliseconds automatically. If timeout is less than 0, then automatic cache flushing is disabled.

Parameters

[in]	size	The size of the cache in kibibytes.
[in]	timeout	The timeout between cache flushes.

See also: FlushCache()

Definition at line 120 of file resourceloader.cpp.

◆ SetNameFilters()

void LC::Util::ResourceLoader::SetNameFilters ( const QStringList & filters )

Sets the name filters for the subelement model.

Wildcards may be used in name fitlers. Use an empty QStringList to disable filtering. By default, no filter is set.

This is analogous to QDir's functions for filtering its results.

Note: This function should be called before any paths are registered in this resource loader, otherwise unwanted results may occur in the subelement model.

See also: SetAttrFilters(), GetSubElemModel()

Definition at line 297 of file resourceloader.cpp.

◆ SetVerbose()

void LC::Util::ResourceLoader::SetVerbose ( bool verbose )

Control whether the ResourceLoader prints what it is doing to the logs.

Parameters

verbose If true, the loader will print more debug statements to the logs.

Definition at line 302 of file resourceloader.cpp.

◆ watchedDirectoriesChanged

void LC::Util::ResourceLoader::watchedDirectoriesChanged ( )

signal

The documentation for this class was generated from the following files:

/home/d34df00d/leechcraft/src/util/sys/resourceloader.h
/home/d34df00d/leechcraft/src/util/sys/resourceloader.cpp

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ResourceLoader()

Member Function Documentation

◆ AddGlobalPrefix()

◆ AddLocalPrefix()

◆ FlushCache()

◆ GetIconDevice()

◆ GetIconPath()

◆ GetPath()

◆ GetSubElemModel()

◆ List()

◆ Load() [1/2]

◆ Load() [2/2]

◆ LoadPixmap()

◆ SetAttrFilters()

◆ SetCacheParams()

◆ SetNameFilters()

◆ SetVerbose()

◆ watchedDirectoriesChanged