Digikam::AlbumManager Class Reference

There are two primary managers which manage the listing and lifetime of Album and ImageInfo: AlbumManager and AlbumLister. More...

#include <albummanager.h>

Inheritance diagram for Digikam::AlbumManager:

[legend]

List of all members.

Signals
void	signalAlbumAboutToBeAdded (Album album, Album parent, Album *prev)
void	signalAlbumAboutToBeDeleted (Album *album)
void	signalAlbumAdded (Album *album)
void	signalAlbumCurrentChanged (Album *album)
void	signalAlbumDeleted (Album *album)
void	signalAlbumHasBeenDeleted (void *)
void	signalAlbumIconChanged (Album *album)
void	signalAlbumRenamed (Album *album)
void	signalAlbumsCleared ()
void	signalAllAlbumsLoaded ()
void	signalAllDAlbumsLoaded ()
void	signalDAlbumsDirty (const QMap< YearMonth, int > &)
void	signalDatesMapDirty (const QMap< QDateTime, int > &)
void	signalPAlbumsDirty (const QMap< int, int > &)
void	signalSearchUpdated (SAlbum *album)
void	signalTAlbumMoved (TAlbum album, TAlbum newParent)
void	signalTAlbumsDirty (const QMap< int, int > &)
Public Member Functions
QHash< int, QString >	albumTitles () const
List of Albums and current Album

AlbumList	allDAlbums () const
AlbumList	allPAlbums () const
AlbumList	allSAlbums () const
AlbumList	allTAlbums () const
Album *	currentAlbum () const
void	setCurrentAlbum (Album *album)
Operations on PAlbum

PAlbum *	createPAlbum (const CollectionLocation &location, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg)
PAlbum *	createPAlbum (const QString &albumRootPath, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg)
PAlbum *	createPAlbum (PAlbum *parent, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg)
bool	renamePAlbum (PAlbum *album, const QString &newName, QString &errMsg)
bool	updatePAlbumIcon (PAlbum *album, qlonglong iconID, QString &errMsg)
Operations on SAlbum

SAlbum *	createSAlbum (const QString &name, DatabaseSearch::Type type, const QString &query)
bool	deleteSAlbum (SAlbum *album)
bool	updateSAlbum (SAlbum *album, const QString &changedQuery, const QString &changedName=QString(), DatabaseSearch::Type type=DatabaseSearch::UndefinedType)
Operations on TAlbum

TAlbum *	createTAlbum (TAlbum *parent, const QString &name, const QString &iconkde, QString &errMsg)
bool	deleteTAlbum (TAlbum *album, QString &errMsg)
AlbumList	findOrCreateTAlbums (const QStringList &tagPaths)
AlbumList	getRecentlyAssignedTags () const
bool	moveTAlbum (TAlbum album, TAlbum newParent, QString &errMsg)
bool	renameTAlbum (TAlbum *album, const QString &name, QString &errMsg)
QHash< int, QString >	tagNames () const
QStringList	tagNames (const QList< int > &tagIDs) const
QHash< int, QString >	tagPaths (bool leadingSlash=true) const
QStringList	tagPaths (const QList< int > &tagIDs, bool leadingSlash=true) const
bool	updateTAlbumIcon (TAlbum *album, const QString &iconKDE, qlonglong iconID, QString &errMsg)
Finding Albums

Album *	findAlbum (int gid) const
DAlbum *	findDAlbum (int id) const
PAlbum *	findPAlbum (int id) const
PAlbum *	findPAlbum (const KUrl &url) const
SAlbum *	findSAlbum (const QString &name) const
SAlbum *	findSAlbum (int id) const
TAlbum *	findTAlbum (const QString &tagPath) const
TAlbum *	findTAlbum (int id) const
Static Public Member Functions
static AlbumManager *	instance ()
Library path And Scanning

static void	checkDatabaseDirsAfterFirstRun (const QString &dbPath, const QString &albumPath)
void	changeDatabase (const QString &dbPath)
void	cleanUp ()
bool	databaseEqual (const QString &dbPath) const
void	prepareItemCounts ()
void	refresh ()
bool	setDatabase (const QString &dbPath, bool priority, const QString &suggestedAlbumRoot=QString())
void	startScan ()

Detailed Description

There are two primary managers which manage the listing and lifetime of Album and ImageInfo: AlbumManager and AlbumLister.

AlbumManager manages albums: does listing of albums and controls the lifetime of it. For PAlbums and TAlbums, the listing is done by reading the db directly and building the hierarchy of the albums. For DAlbums, since the listing takes time, the work is delegated to a kioslave. Interested frontend entities can connect to the albummanager to receive notifications of new Albums, when Albums are deleted and when the current album is changed.

Additional operations are provided for: creating/deleting/rename Albums, updating icons and moving Albums.

Definition at line 90 of file albummanager.h.

Member Function Documentation

QHash< int, QString > Digikam::AlbumManager::albumTitles ( ) const

Returns:: A hash with the titles for all album IDs.

Definition at line 2279 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::allDAlbums ( ) const

Returns:: a list of all DAlbums

Definition at line 1612 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::allPAlbums ( ) const

Returns:: a list of all PAlbums

Definition at line 1564 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::allSAlbums ( ) const

Returns:: a list of all SAlbums

Definition at line 1596 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::allTAlbums ( ) const

Returns:: a list of all TAlbums

Definition at line 1580 of file albummanager.cpp.

void Digikam::AlbumManager::changeDatabase ( const QString & dbPath )

Sets new database when chosen by the user in setup.

Handles user notification about problems. Call this instead of setDatabase when digikam is up and running.

Definition at line 428 of file albummanager.cpp.

void Digikam::AlbumManager::checkDatabaseDirsAfterFirstRun	(	const QString &	dbPath,
		const QString &	albumPath
	)			`[static]`

Some checks for settings done in first run wizard.

Definition at line 383 of file albummanager.cpp.

void Digikam::AlbumManager::cleanUp ( )

Stop ongoing operations, prepare for application shutdown.

Definition at line 317 of file albummanager.cpp.

PAlbum * Digikam::AlbumManager::createPAlbum	(	const CollectionLocation &	location,
		const QString &	name,
		const QString &	caption,
		const QDate &	date,
		const QString &	category,
		QString &	errMsg
	)

Overloaded method.

Here you can supply a collection location (which must be available).

Definition at line 1759 of file albummanager.cpp.

PAlbum * Digikam::AlbumManager::createPAlbum	(	const QString &	albumRootPath,
		const QString &	name,
		const QString &	caption,
		const QDate &	date,
		const QString &	category,
		QString &	errMsg
	)

Overloaded method.

Here you can supply an albumRootPath which must correspond to an available collection location.

Definition at line 1750 of file albummanager.cpp.

PAlbum * Digikam::AlbumManager::createPAlbum	(	PAlbum *	parent,
		const QString &	name,
		const QString &	caption,
		const QDate &	date,
		const QString &	category,
		QString &	errMsg
	)

Create a new PAlbum with supplied properties as a child of the parent This is equivalent to creating a new folder on the disk with supplied name in the parent's folder path.

Also the supplied attributes are written out to the database

Note:: the signalAlbumAdded will be fired before this function returns. Its recommended to connect to that signal to get notification of new album added

Returns:: the newly created PAlbum or 0 if it fails

Parameters:

	parent	The parent album under which to create the new Album. Parent must not be root. Otherwise, use the other variants of this method. If parent is root, the albumRootPath must be supplied.
	name	the name of the new album
	caption	the caption for the new album
	date	the date for the new album
	collection	the collection for the new album
	errMsg	this will contain the error message describing why the operation failed

Definition at line 1782 of file albummanager.cpp.

SAlbum * Digikam::AlbumManager::createSAlbum	(	const QString &	name,
		DatabaseSearch::Type	type,
		const QString &	query
	)

Create a new SAlbum with supplied url.

If an existing SAlbum with same name exists this function will return a pointer to that album, instead of creating a new one. A newly created search album is added to the database. For an existing SAlbum, the url is updated and written out to the database

Note:: the signalAlbumAdded will be fired before this function returns. Its recommended to connect to that signal to get notification of new album added

Returns:: the newly created SAlbum or an existing SAlbum with same name

Parameters:

	url	the url of the album
	simple	indicates whether the Search album is of simple type or extended type

Definition at line 2292 of file albummanager.cpp.

TAlbum * Digikam::AlbumManager::createTAlbum	(	TAlbum *	parent,
		const QString &	name,
		const QString &	iconkde,
		QString &	errMsg
	)

Create a new TAlbum with supplied properties as a child of the parent The tag is added to the database.

Note:: the signalAlbumAdded will be fired before this function returns. Its recommended to connect to that signal to get notification of new album added

Returns:: the newly created TAlbum or 0 if it fails

Parameters:

	parent	the parent album under which to create the new Album
	name	the name of the new album
	iconkde	the iconkde for the new album (this is a filename which kde iconloader can load up
	errMsg	this will contain the error message describing why the operation failed

Definition at line 1997 of file albummanager.cpp.

Album * Digikam::AlbumManager::currentAlbum ( ) const

Returns:: the current album

Definition at line 1634 of file albummanager.cpp.

bool Digikam::AlbumManager::databaseEqual ( const QString & dbPath ) const

Checks if the given database path is equal to the current one.

Definition at line 343 of file albummanager.cpp.

bool Digikam::AlbumManager::deleteSAlbum ( SAlbum * album )

Delete a SAlbum from the database.

Note:: the signalAlbumDeleted will be fired before this function returns. Its recommended to connect to that signal to get notification of album deletes

Returns:: true if the operation succeeds, false otherwise

Parameters:

album

the album to delete

Definition at line 2344 of file albummanager.cpp.

bool Digikam::AlbumManager::deleteTAlbum	(	TAlbum *	album,
		QString &	errMsg
	)

Delete a TAlbum.

The tag is removed from the database

Note:: the signalAlbumDeleted will be fired before this function returns. Its recommended to connect to that signal to get notification of album deletes

Returns:: true if the operation succeeds or false otherwise

Parameters:

	album	the TAlbum to delete
	errMsg	this will contain the error message describing why the operation failed

Definition at line 2065 of file albummanager.cpp.

Album * Digikam::AlbumManager::findAlbum ( int gid ) const

Returns:: a Album with the given globalID

Parameters:

gid

the global id for the album

Definition at line 1687 of file albummanager.cpp.

DAlbum * Digikam::AlbumManager::findDAlbum ( int id ) const

Returns:: a DAlbum with given ID

Parameters:

id

the id for the DAlbum

Definition at line 1677 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::findOrCreateTAlbums ( const QStringList & tagPaths )

A list of tag paths is supplied.

If no corresponding TAlbum exists, a new one will be created.

Parameters:

tagPath

A list of tag paths

Returns:: A list of all TAlbums for the list (already existing or newly created)

Definition at line 2047 of file albummanager.cpp.

PAlbum * Digikam::AlbumManager::findPAlbum ( int id ) const

Returns:: a PAlbum with given ID

Parameters:

id

the id for the PAlbum

Definition at line 1647 of file albummanager.cpp.

PAlbum * Digikam::AlbumManager::findPAlbum ( const KUrl & url ) const

Given a complete file url (kde url with file protocol), it will try to find a PAlbum corresponding to it.

Warning:: This should not be used, unless really necessary

Returns:: PAlbum corresponding to supplied url

Parameters:

url

the url we need to check

Definition at line 1639 of file albummanager.cpp.

SAlbum * Digikam::AlbumManager::findSAlbum ( const QString & name ) const

Returns:: a SAlbum with given name, or 0 if not found

Parameters:

tagPath

the name of the search

Definition at line 1708 of file albummanager.cpp.

SAlbum * Digikam::AlbumManager::findSAlbum ( int id ) const

Returns:: a SAlbum with given ID

Parameters:

id

the id for the SAlbum

Definition at line 1667 of file albummanager.cpp.

TAlbum * Digikam::AlbumManager::findTAlbum ( const QString & tagPath ) const

Returns:: a TAlbum with given tag path, or 0 if not found

Parameters:

tagPath

the tag path ("People/Friend/John")

Definition at line 1692 of file albummanager.cpp.

TAlbum * Digikam::AlbumManager::findTAlbum ( int id ) const

Returns:: a TAlbum with given ID

Parameters:

id

the id for the TAlbum

Definition at line 1657 of file albummanager.cpp.

AlbumList Digikam::AlbumManager::getRecentlyAssignedTags ( ) const

Get a list of recently assigned tags (only last 6 tags are listed).

Returns:: the list of recently assigned TAlbums

Definition at line 2207 of file albummanager.cpp.

AlbumManager * Digikam::AlbumManager::instance ( ) [static]

A convenience function to get the instance of the AlbumManager.

Definition at line 256 of file albummanager.cpp.

bool Digikam::AlbumManager::moveTAlbum	(	TAlbum *	album,
		TAlbum *	newParent,
		QString &	errMsg
	)

Move a TAlbum to a new parent.

This updates the tag parent ID in the database

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the Album which should be moved
	newParent	the Parent Album to which album should be moved
	errMsg	this will contain the error message describing why the operation failed

Definition at line 2140 of file albummanager.cpp.

void Digikam::AlbumManager::prepareItemCounts ( )

Ensures that valid item counts for physical and tag albums are available.

Definition at line 1083 of file albummanager.cpp.

void Digikam::AlbumManager::refresh ( )

This is similar to startScan, except that it assumes you have run startScan at least once.

It checks the database to see if any new albums have been added and updates them accordingly. Use this when a change in the filesystem is detected (but the album library path hasn't changed)

See also:: startScan

Definition at line 1075 of file albummanager.cpp.

bool Digikam::AlbumManager::renamePAlbum	(	PAlbum *	album,
		const QString &	newName,
		QString &	errMsg
	)

Renames a PAlbum.

This is equivalent to actually renaming the corresponding folder on the disk.

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the Album which should be renamed
	newName	the new name for the album
	errMsg	this will contain the error message describing why the operation failed

Definition at line 1862 of file albummanager.cpp.

bool Digikam::AlbumManager::renameTAlbum	(	TAlbum *	album,
		const QString &	name,
		QString &	errMsg
	)

Renames a TAlbum.

This updates the tag name in the database

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the Album which should be renamed
	name	the new name for the album
	errMsg	this will contain the error message describing why the operation failed

Definition at line 2098 of file albummanager.cpp.

void Digikam::AlbumManager::setCurrentAlbum ( Album * album )

set the current album to album.

Call this from views which show listing of albums. This also causes it to fire the signal signalAlbumCurrentChanged()

Definition at line 1628 of file albummanager.cpp.

bool Digikam::AlbumManager::setDatabase	(	const QString &	dbPath,
		bool	priority,
		const QString &	suggestedAlbumRoot = `QString()`
	)

Initialize.

Informs the user about failures. Returns true on success, false on failure. A return value of false during startup indicates termination of the program (user is informed)

Definition at line 534 of file albummanager.cpp.

void Digikam::AlbumManager::signalAlbumAboutToBeAdded	(	Album *	album,
		Album *	parent,
		Album *	prev
	)			`[signal]`

An album is about to be added to the given parent (0 if album is root) after the item given by prev (prev is 0 if parent has no children yet).

void Digikam::AlbumManager::signalAlbumAboutToBeDeleted ( Album * album ) [signal]

The album is about to be deleted, but is still fully valid.

void Digikam::AlbumManager::signalAlbumAdded ( Album * album ) [signal]

The album has been added.

void Digikam::AlbumManager::signalAlbumCurrentChanged ( Album * album ) [signal]

void Digikam::AlbumManager::signalAlbumDeleted ( Album * album ) [signal]

The album is deleted, but the object can still be accessed.

void Digikam::AlbumManager::signalAlbumHasBeenDeleted ( void * ) [signal]

The album is deleted, the object can no longer be accessed.

For identification purposes, the former album pointer is passed.

void Digikam::AlbumManager::signalAlbumIconChanged ( Album * album ) [signal]

void Digikam::AlbumManager::signalAlbumRenamed ( Album * album ) [signal]

void Digikam::AlbumManager::signalAlbumsCleared ( ) [signal]

void Digikam::AlbumManager::signalAllAlbumsLoaded ( ) [signal]

void Digikam::AlbumManager::signalAllDAlbumsLoaded ( ) [signal]

void Digikam::AlbumManager::signalDAlbumsDirty ( const QMap< YearMonth, int > & ) [signal]

void Digikam::AlbumManager::signalDatesMapDirty ( const QMap< QDateTime, int > & ) [signal]

void Digikam::AlbumManager::signalPAlbumsDirty ( const QMap< int, int > & ) [signal]

void Digikam::AlbumManager::signalSearchUpdated ( SAlbum * album ) [signal]

void Digikam::AlbumManager::signalTAlbumMoved	(	TAlbum *	album,
		TAlbum *	newParent
	)			`[signal]`

void Digikam::AlbumManager::signalTAlbumsDirty ( const QMap< int, int > & ) [signal]

void Digikam::AlbumManager::startScan ( )

starts scanning the libraryPath and listing the albums.

If the libraryPath has not changed since the lastscan, then nothing happens

See also:: setLibraryPath; refresh

Definition at line 938 of file albummanager.cpp.

QHash< int, QString > Digikam::AlbumManager::tagNames ( ) const

Returns:: A hash with the tag names for all tag IDs.

Definition at line 2266 of file albummanager.cpp.

QStringList Digikam::AlbumManager::tagNames ( const QList< int > & tagIDs ) const

Returns:: A list with the tag names for a list of tag IDs.

Parameters:

tagIDs

list of tag album IDs

Definition at line 2237 of file albummanager.cpp.

QHash< int, QString > Digikam::AlbumManager::tagPaths ( bool leadingSlash = true ) const

Returns:: A hash with the tag paths for all tag IDs.

Definition at line 2253 of file albummanager.cpp.

QStringList Digikam::AlbumManager::tagPaths	(	const QList< int > &	tagIDs,
		bool	leadingSlash = `true`
	)			const

Returns:: A list with the tag paths for a list of tag IDs.

Parameters:

tagIDs

list of tag album IDs

Definition at line 2221 of file albummanager.cpp.

bool Digikam::AlbumManager::updatePAlbumIcon	(	PAlbum *	album,
		qlonglong	iconID,
		QString &	errMsg
	)

Update the icon for an album.

The icon is the name (and not full path) of the file in the album

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the album for which icon should be changed
	iconID	the filename of the new icon
	errMsg	if the operation fails, this will contain the error message describing why the operation failed

Definition at line 1963 of file albummanager.cpp.

bool Digikam::AlbumManager::updateSAlbum	(	SAlbum *	album,
		const QString &	changedQuery,
		const QString &	changedName = `QString()`,
		DatabaseSearch::Type	type = `DatabaseSearch::UndefinedType`
	)

Update the url for a SAlbum.

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the album to update
	query	the new query data of the album
	changedName	a new name, or null to keep the current name
	type	a new type, or UndefinedType to keep the current type

Definition at line 2322 of file albummanager.cpp.

bool Digikam::AlbumManager::updateTAlbumIcon	(	TAlbum *	album,
		const QString &	iconKDE,
		qlonglong	iconID,
		QString &	errMsg
	)

Update the icon for a TAlbum.

Returns:: true if the operation succeeds, false otherwise

Parameters:

	album	the album for which icon should be changed
	iconKDE	a simple filename which can be loaded by KIconLoader
	iconID	id of the icon image file
	errMsg	this will contain the error message describing why the operation failed

Note:: if iconKDE is not empty then iconID is used. So if you want to set the icon to a file which can be loaded by KIconLoader, pass it in as iconKDE. otherwise pass a null QString to iconKDE and set iconID

Definition at line 2165 of file albummanager.cpp.

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

digikam

Digikam::AlbumManager Class Reference

Signals

Public Member Functions

Static Public Member Functions

Library path And Scanning

Detailed Description

Member Function Documentation

digikam

API Reference