digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
Digikam::AlbumManager Class Reference

AlbumManager manages albums: does listing of albums and controls the lifetime of it. More...

+ Inheritance diagram for Digikam::AlbumManager:

Public Member Functions

void cleanUp ()
 Stop ongoing operations, prepare for application shutdown.
 
bool isShowingOnlyAvailableAlbums () const
 
void prepareItemCounts ()
 Ensures that valid item counts for physical and tag albums are available.
 
void refresh ()
 This is similar to startScan, except that it assumes you have run startScan at least once.
 
void setShowOnlyAvailableAlbums (bool onlyAvailable)
 
void startScan ()
 starts scanning the libraryPath and listing the albums.
 

Static Public Member Functions

static AlbumManagerinstance ()
 A convenience function to get the instance of the AlbumManager.
 

Operations on Face Album

class AlbumManagerCreator
 
template<class T >
class AlbumPointer
 
class Album
 
QHash< int, int > getFaceCount () const
 Returns the latest count for faces as also emitted via signalFaceCountsDirty.
 
QHash< int, int > getUnconfirmedFaceCount () const
 Returns the latest count for unconfirmed faces only as also emitted via signalFaceCountsDirty.
 
void signalFaceCountsDirty (const QHash< int, int > &faceCount, const QHash< int, int > &uFaceCount, const QList< int > &toUpdatedFaces)
 

Operations with database

static void checkDatabaseDirsAfterFirstRun (const QString &dbPath, const QString &albumPath)
 Some checks for settings done in first run wizard in case of QSlite Database.
 
bool setDatabase (const DbEngineParameters &params, bool priority, const QString &suggestedAlbumRoot=QString(), bool ignoreDisappearedLocations=false)
 Initialize.
 
void changeDatabase (const DbEngineParameters &params)
 Sets new database when chosen by the user in setup.
 
bool databaseEqual (const DbEngineParameters &parameters) const
 Checks if the given database path is equal to the current one.
 

Operations on generic Album

void setCurrentAlbums (const QList< Album * > &albums)
 set current album to albums.
 
AlbumList currentAlbums () const
 
void clearCurrentAlbums ()
 clear current albums.
 
AlbumfindAlbum (int gid) const
 
AlbumfindAlbum (Album::Type type, int id) const
 
QHash< int, QString > albumTitles () const
 
bool isMovingAlbum (Album *album) const
 Returns if the given album is currently being moved, that is, if this album is in between signalAlbumAboutToBeMoved and signalAlbumMoved.
 
qlonglong getItemFromAlbum (Album *const album, const QString &fileName)
 Returns the id of the item with the given filename in the given Album.
 
void signalAlbumAboutToBeAdded (Album *album, Album *parent, Album *prev)
 Emitted when 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 signalAlbumAdded (Album *album)
 Emitted when the album has been added.
 
void signalAlbumAboutToBeDeleted (Album *album)
 Emitted when the album is about to be deleted, but is still fully valid.
 
void signalAlbumDeleted (Album *album)
 Emitted when the album is deleted, but the object can still be accessed.
 
void signalAlbumHasBeenDeleted (Album *album)
 Emitted when the album is deleted, the object can no longer be accessed.
 
void signalAlbumsCleared ()
 
void signalAlbumCurrentChanged (const QList< Album * > &albums)
 
void signalAllAlbumsLoaded ()
 
void signalAlbumIconChanged (Album *album)
 
void signalAlbumRenamed (Album *album)
 
void signalAlbumNewPath (Album *album)
 
void signalAlbumAboutToBeMoved (Album *album)
 Emittedd when an album is about to be moved.
 
void signalAlbumMoved (Album *album)
 Emitted when the album is moved to its new parent.
 
void signalAlbumsUpdated (int type)
 
void signalShowOnlyAvailableAlbumsChanged (bool showsOnlyAvailableAlbums)
 Emitted when a change is done on available Albums.
 

Operations on Date Album

AlbumList allDAlbums () const
 
DAlbumfindDAlbum (int id) const
 
QMap< YearMonth, int > getDAlbumsCount () const
 Returns the latest count for DAlbums as also emitted via signalDAlbumsDirty.
 
void signalDAlbumsDirty (const QMap< YearMonth, int > &)
 
void signalDatesHashDirty (const QHash< QDateTime, int > &)
 
void signalAllDAlbumsLoaded ()
 

Operations on Physical Album

AlbumList allPAlbums () const
 
PAlbumcurrentPAlbum () const
 
PAlbumfindPAlbum (const QUrl &url) const
 Given a complete file url (kde url with file protocol), it will try to find a PAlbum corresponding to it.
 
PAlbumfindPAlbum (int id) const
 
QHash< int, int > getPAlbumsCount () const
 Returns the latest count for PAlbums as also emitted via signalPAlbumsDirty.
 
void removeWatchedPAlbums (const PAlbum *const album)
 
PAlbumcreatePAlbum (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.
 
PAlbumcreatePAlbum (const QString &albumRootPath, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg)
 Overloaded method.
 
PAlbumcreatePAlbum (const CollectionLocation &location, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg)
 Overloaded method.
 
bool renamePAlbum (PAlbum *album, const QString &newName, QString &errMsg)
 Renames a PAlbum.
 
bool updatePAlbumIcon (PAlbum *album, qlonglong iconID, QString &errMsg)
 Update the icon for an album.
 
void signalPAlbumsDirty (const QHash< int, int > &)
 
void signalEmptyTrash ()
 

Operations on Tag Album

AlbumList allTAlbums () const
 
QList< TAlbum * > currentTAlbums () const
 This method is not yet used.
 
TAlbumfindTAlbum (int id) const
 
TAlbumfindTAlbum (const QString &tagPath) const
 
QHash< int, int > getTAlbumsCount () const
 Returns the latest count for TAlbums as also emitted via signalTAlbumsDirty.
 
TAlbumcreateTAlbum (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.
 
AlbumList findOrCreateTAlbums (const QStringList &tagPaths)
 A list of tag paths is supplied.
 
bool deleteTAlbum (TAlbum *album, QString &errMsg, QList< qlonglong > *imageIds=nullptr)
 Delete a TAlbum.
 
bool renameTAlbum (TAlbum *album, const QString &name, QString &errMsg)
 Renames a TAlbum.
 
bool moveTAlbum (TAlbum *album, TAlbum *newParent, QString &errMsg)
 Move a TAlbum to a new parent.
 
bool mergeTAlbum (TAlbum *album, TAlbum *destAlbum, bool dialog, QString &errMsg)
 Merge a TAlbum to a TAlbum.
 
bool updateTAlbumIcon (TAlbum *album, const QString &iconKDE, qlonglong iconID, QString &errMsg)
 Update the icon for a TAlbum.
 
AlbumList getRecentlyAssignedTags (bool includeInternal=false) const
 Get a list of recently assigned tags (only last 6 tags are listed)
 
QStringList tagPaths (const QList< int > &tagIDs, bool leadingSlash=true, bool includeInternal=false) const
 Return A list with the tag paths for a list of tag IDs.
 
QStringList tagNames (const QList< int > &tagIDs, bool includeInternal=false) const
 
QHash< int, QString > tagPaths (bool leadingSlash=true, bool includeInternal=false) const
 
QHash< int, QString > tagNames (bool includeInternal=false) const
 
AlbumList findTagsWithProperty (const QString &property)
 Returns a list of TAlbums which have the given property, or the given property/value combination.
 
AlbumList findTagsWithProperty (const QString &property, const QString &value)
 
QList< int > subTags (int tagId, bool recursive=false) const
 TODO.
 
int findTopId (int tagId) const
 
void askUserForWriteChangedTAlbumToFiles (TAlbum *const album)
 
void askUserForWriteChangedTAlbumToFiles (const QList< qlonglong > &imageIds)
 
void signalTAlbumsDirty (const QHash< int, int > &)
 
void signalTagPropertiesChanged (TAlbum *album)
 

Operations on Search Album

AlbumList allSAlbums () const
 
SAlbumfindSAlbum (int id) const
 
SAlbumfindSAlbum (const QString &name) const
 
QList< SAlbum * > findSAlbumsBySearchType (int searchType) const
 
SAlbumcreateSAlbum (const QString &name, DatabaseSearch::Type type, const QString &query)
 Create a new SAlbum with supplied url.
 
bool updateSAlbum (SAlbum *album, const QString &changedQuery, const QString &changedName=QString(), DatabaseSearch::Type type=DatabaseSearch::UndefinedType)
 Update the url for a SAlbum.
 
bool deleteSAlbum (SAlbum *album)
 Delete a SAlbum from the database.
 
void signalUpdateDuplicatesAlbums (const QList< SAlbum * > &modifiedAlbums, const QList< qlonglong > &deletedImages)
 
void signalSearchUpdated (SAlbum *album)
 

Detailed Description

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 dbjob. 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.

Member Function Documentation

◆ albumTitles()

QHash< int, QString > Digikam::AlbumManager::albumTitles ( ) const
Returns
A hash with the titles for all album IDs.

◆ allDAlbums()

AlbumList Digikam::AlbumManager::allDAlbums ( ) const
Returns
a list of all DAlbums

◆ allPAlbums()

AlbumList Digikam::AlbumManager::allPAlbums ( ) const
Returns
a list of all PAlbums

◆ allSAlbums()

AlbumList Digikam::AlbumManager::allSAlbums ( ) const
Returns
a list of all SAlbums

◆ allTAlbums()

AlbumList Digikam::AlbumManager::allTAlbums ( ) const
Returns
a list of all TAlbums

◆ changeDatabase()

void Digikam::AlbumManager::changeDatabase ( const DbEngineParameters params)

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

◆ createPAlbum() [1/3]

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

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

Parameters
locationthe collection for the new album
namethe name of the new album
captionthe caption for the new album
datethe date for the new album
categorythe category for the new album
errMsgthis will contain the error message describing why the operation failed

◆ createPAlbum() [2/3]

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

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

◆ createPAlbum() [3/3]

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

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
parentthe 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.
namethe name of the new album
captionthe caption for the new album
datethe date for the new album
categorythe category for the new album
errMsgthis will contain the error message describing why the operation failed

◆ createSAlbum()

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

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
namename for the new search
typethe type of the search
querysearch query to use

◆ createTAlbum()

TAlbum * Digikam::AlbumManager::createTAlbum ( TAlbum parent,
const QString &  name,
const QString &  iconkde,
QString &  errMsg 
)
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
parentthe parent album under which to create the new Album
namethe name of the new album
iconkdethe iconkde for the new album (this is a filename which kde iconloader can load up
errMsgthis will contain the error message describing why the operation failed

◆ currentAlbums()

AlbumList Digikam::AlbumManager::currentAlbums ( ) const
Returns
current albums, previously set up by setCurrentAlbums

◆ currentPAlbum()

PAlbum * Digikam::AlbumManager::currentPAlbum ( ) const
Returns
the current PAlbum or null if no one is selected

Temporary fix, to return multiple items, iterate and cast each element

◆ currentTAlbums()

QList< TAlbum * > Digikam::AlbumManager::currentTAlbums ( ) const
Returns
the current TAlbum or null if no one is selected

◆ deleteSAlbum()

bool Digikam::AlbumManager::deleteSAlbum ( SAlbum album)
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
albumthe album to delete

◆ deleteTAlbum()

bool Digikam::AlbumManager::deleteTAlbum ( TAlbum album,
QString &  errMsg,
QList< qlonglong > *  imageIds = nullptr 
)

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
albumthe TAlbum to delete
errMsgthis will contain the error message describing why the
imageIdslist of image ID from the database where tag is removed

◆ findAlbum() [1/2]

Album * Digikam::AlbumManager::findAlbum ( Album::Type  type,
int  id 
) const
Returns
a Album with the given type and id
Parameters
typethe type of album
idthe id for the album (not the global id)

◆ findAlbum() [2/2]

Album * Digikam::AlbumManager::findAlbum ( int  gid) const
Returns
a Album with the given globalID
Parameters
gidthe global id for the album

◆ findDAlbum()

DAlbum * Digikam::AlbumManager::findDAlbum ( int  id) const
Returns
a DAlbum with given ID
Parameters
idthe id for the DAlbum

◆ findOrCreateTAlbums()

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

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

Parameters
tagPathsA list of tag paths
Returns
A list of all TAlbums for the list (already existing or newly created)

◆ findPAlbum() [1/2]

PAlbum * Digikam::AlbumManager::findPAlbum ( const QUrl &  url) const
Warning
This should not be used, unless really necessary
Returns
PAlbum corresponding to supplied url
Parameters
urlthe url we need to check

◆ findPAlbum() [2/2]

PAlbum * Digikam::AlbumManager::findPAlbum ( int  id) const
Returns
a PAlbum with given ID
Parameters
idthe id for the PAlbum

◆ findSAlbum() [1/2]

SAlbum * Digikam::AlbumManager::findSAlbum ( const QString &  name) const
Returns
a SAlbum with given name, or 0 if not found
Parameters
namethe name of the search

◆ findSAlbum() [2/2]

SAlbum * Digikam::AlbumManager::findSAlbum ( int  id) const
Returns
a SAlbum with given ID
Parameters
idthe id for the SAlbum

◆ findSAlbumsBySearchType()

QList< SAlbum * > Digikam::AlbumManager::findSAlbumsBySearchType ( int  searchType) const
Returns
SAlbums with given type, empty list if not found
Parameters
searchTypethe type of the search

◆ findTAlbum() [1/2]

TAlbum * Digikam::AlbumManager::findTAlbum ( const QString &  tagPath) const
Returns
a TAlbum with given tag path, or 0 if not found
Parameters
tagPaththe tag path ("People/Friend/John")

◆ findTAlbum() [2/2]

TAlbum * Digikam::AlbumManager::findTAlbum ( int  id) const
Returns
a TAlbum with given ID
Parameters
idthe id for the TAlbum

◆ getDAlbumsCount()

QMap< YearMonth, int > Digikam::AlbumManager::getDAlbumsCount ( ) const
Returns
count map for DAlbums

◆ getFaceCount()

QHash< int, int > Digikam::AlbumManager::getFaceCount ( ) const
Returns
count map for faces (confirmed and unconfirmed combined)

◆ getItemFromAlbum()

qlonglong Digikam::AlbumManager::getItemFromAlbum ( Album *const  album,
const QString &  fileName 
)
Parameters
albumThe album in which we search the item.
fileNameThe name of the item file.
Returns
The item id or -1 if not existent.

◆ getPAlbumsCount()

QHash< int, int > Digikam::AlbumManager::getPAlbumsCount ( ) const
Returns
count map for PAlbums

◆ getRecentlyAssignedTags()

AlbumList Digikam::AlbumManager::getRecentlyAssignedTags ( bool  includeInternal = false) const
Returns
the list of recently assigned TAlbums
Parameters
includeInternalinclude internal tags in the returned list, or skip them

◆ getTAlbumsCount()

QHash< int, int > Digikam::AlbumManager::getTAlbumsCount ( ) const
Returns
count map for TAlbums

◆ getUnconfirmedFaceCount()

QHash< int, int > Digikam::AlbumManager::getUnconfirmedFaceCount ( ) const
Returns
count map for unconfirmed faces only

◆ isMovingAlbum()

bool Digikam::AlbumManager::isMovingAlbum ( Album album) const

In this case, you can preserve state of such an album because the object is guaranteed not to be deleted, even if signalAlbumAboutToBeDeleted is emitted.

◆ mergeTAlbum()

bool Digikam::AlbumManager::mergeTAlbum ( TAlbum album,
TAlbum destAlbum,
bool  dialog,
QString &  errMsg 
)

This updates the image tags in the database

Returns
true if the operation succeeds, false otherwise
Parameters
albumthe Album which should be merged
destAlbumthe Album to which album should be merged
dialogshow dialog to ask the user if he wants to merge
errMsgthis will contain the error message describing why the operation failed

◆ moveTAlbum()

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

This updates the tag parent ID in the database

Returns
true if the operation succeeds, false otherwise
Parameters
albumthe Album which should be moved
newParentthe Parent Album to which album should be moved
errMsgthis will contain the error message describing why the operation failed

◆ refresh()

void Digikam::AlbumManager::refresh ( )

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

◆ renamePAlbum()

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

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

Returns
true if the operation succeeds, false otherwise
Parameters
albumthe Album which should be renamed
newNamethe new name for the album
errMsgthis will contain the error message describing why the operation failed

◆ renameTAlbum()

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

This updates the tag name in the database

Returns
true if the operation succeeds, false otherwise
Parameters
albumthe Album which should be renamed
namethe new name for the album
errMsgthis will contain the error message describing why the operation failed

◆ setCurrentAlbums()

void Digikam::AlbumManager::setCurrentAlbums ( const QList< Album * > &  albums)

Filter out the null pointers

Sort is needed to identify selection correctly, ex AlbumHistory

◆ setDatabase()

bool Digikam::AlbumManager::setDatabase ( const DbEngineParameters params,
bool  priority,
const QString &  suggestedAlbumRoot = QString(),
bool  ignoreDisappearedLocations = false 
)

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)

ignoreDisappearedLocations is intended to be used in tests, because the path of the collection is hardcoded but when executing the test on different computers the collection might not be available at that path

◆ signalAlbumAboutToBeMoved

void Digikam::AlbumManager::signalAlbumAboutToBeMoved ( Album album)
signal

Signals for deleting and adding will be sent afterwards, but the album object is guaranteed not to be deleted until after signalAlbumMoved.

◆ signalAlbumHasBeenDeleted

void Digikam::AlbumManager::signalAlbumHasBeenDeleted ( Album album)
signal

For identification purposes, the former album pointer is passed.

◆ signalAlbumMoved

void Digikam::AlbumManager::signalAlbumMoved ( Album album)
signal

After signalAlbumAboutToBeMoved, all four signals for first deleting and then adding will have been sent.

◆ signalShowOnlyAvailableAlbumsChanged

void Digikam::AlbumManager::signalShowOnlyAvailableAlbumsChanged ( bool  showsOnlyAvailableAlbums)
signal

Please note that affected albums may appear or disappear after this signal has been emitted.

◆ startScan()

void Digikam::AlbumManager::startScan ( )

If the libraryPath has not changed since the last scan, then nothing happens

See also
setLibraryPath
refresh

◆ tagNames() [1/2]

QHash< int, QString > Digikam::AlbumManager::tagNames ( bool  includeInternal = false) const
Returns
A hash with the tag names for all tag IDs.
Parameters
includeInternalinclude internal tags in the returned list, or skip them

◆ tagNames() [2/2]

QStringList Digikam::AlbumManager::tagNames ( const QList< int > &  tagIDs,
bool  includeInternal = false 
) const
Returns
A list with the tag names for a list of tag IDs.
Parameters
tagIDslist of tag album IDs
includeInternalinclude internal tags in the returned list, or skip them

◆ tagPaths() [1/2]

QHash< int, QString > Digikam::AlbumManager::tagPaths ( bool  leadingSlash = true,
bool  includeInternal = false 
) const
Returns
A hash with the tag paths for all tag IDs.
Parameters
leadingSlashif true return tags with a leading slash
includeInternalinclude internal tags in the returned list, or skip them

◆ tagPaths() [2/2]

QStringList Digikam::AlbumManager::tagPaths ( const QList< int > &  tagIDs,
bool  leadingSlash = true,
bool  includeInternal = false 
) const
Parameters
tagIDslist of tag album IDs
leadingSlashif true return tags with a leading slash
includeInternalinclude internal tags in the returned list, or skip them

◆ updatePAlbumIcon()

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

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

Returns
true if the operation succeeds, false otherwise
Parameters
albumthe album for which icon should be changed
iconIDthe filename of the new icon
errMsgif the operation fails, this will contain the error message describing why the operation failed

◆ updateSAlbum()

bool Digikam::AlbumManager::updateSAlbum ( SAlbum album,
const QString &  changedQuery,
const QString &  changedName = QString(),
DatabaseSearch::Type  type = DatabaseSearch::UndefinedType 
)
Returns
true if the operation succeeds, false otherwise
Parameters
albumthe album to update
changedQuerythe new query data of the album
changedNamea new name, or null to keep the current name
typea new type, or UndefinedType to keep the current type

◆ updateTAlbumIcon()

bool Digikam::AlbumManager::updateTAlbumIcon ( TAlbum album,
const QString &  iconKDE,
qlonglong  iconID,
QString &  errMsg 
)
Returns
true if the operation succeeds, false otherwise
Parameters
albumthe album for which icon should be changed
iconKDEa simple filename which can be loaded by KIconLoader
iconIDid of the icon image file
errMsgthis 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 QIcon, pass it in as iconKDE. otherwise pass a null QString to iconKDE and set iconID