![]() |
digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
|
AlbumManager manages albums: does listing of albums and controls the lifetime of it. More...
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 AlbumManager * | instance () |
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 ¶ms, bool priority, const QString &suggestedAlbumRoot=QString(), bool ignoreDisappearedLocations=false) |
Initialize. | |
void | changeDatabase (const DbEngineParameters ¶ms) |
Sets new database when chosen by the user in setup. | |
bool | databaseEqual (const DbEngineParameters ¶meters) 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. | |
Album * | findAlbum (int gid) const |
Album * | findAlbum (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 |
DAlbum * | findDAlbum (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 |
PAlbum * | currentPAlbum () const |
PAlbum * | findPAlbum (const QUrl &url) const |
Given a complete file url (kde url with file protocol), it will try to find a PAlbum corresponding to it. | |
PAlbum * | findPAlbum (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) |
PAlbum * | 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. | |
PAlbum * | createPAlbum (const QString &albumRootPath, const QString &name, const QString &caption, const QDate &date, const QString &category, QString &errMsg) |
Overloaded method. | |
PAlbum * | createPAlbum (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. | |
TAlbum * | findTAlbum (int id) const |
TAlbum * | findTAlbum (const QString &tagPath) const |
QHash< int, int > | getTAlbumsCount () const |
Returns the latest count for TAlbums as also emitted via signalTAlbumsDirty. | |
TAlbum * | 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. | |
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 |
SAlbum * | findSAlbum (int id) const |
SAlbum * | findSAlbum (const QString &name) const |
QList< SAlbum * > | findSAlbumsBySearchType (int searchType) const |
SAlbum * | createSAlbum (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) |
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.
QHash< int, QString > Digikam::AlbumManager::albumTitles | ( | ) | const |
AlbumList Digikam::AlbumManager::allDAlbums | ( | ) | const |
AlbumList Digikam::AlbumManager::allPAlbums | ( | ) | const |
AlbumList Digikam::AlbumManager::allSAlbums | ( | ) | const |
AlbumList Digikam::AlbumManager::allTAlbums | ( | ) | const |
void Digikam::AlbumManager::changeDatabase | ( | const DbEngineParameters & | params | ) |
Handles user notification about problems. Call this instead of setDatabase when digiKam is up and running.
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).
location | the collection for the new album |
name | the name of the new album |
caption | the caption for the new album |
date | the date for the new album |
category | the category for the new album |
errMsg | this will contain the error message describing why the operation failed |
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.
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
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 |
category | the category for the new album |
errMsg | this will contain the error message describing why the operation failed |
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
name | name for the new search |
type | the type of the search |
query | search query to use |
TAlbum * Digikam::AlbumManager::createTAlbum | ( | TAlbum * | parent, |
const QString & | name, | ||
const QString & | iconkde, | ||
QString & | errMsg | ||
) |
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 |
AlbumList Digikam::AlbumManager::currentAlbums | ( | ) | const |
PAlbum * Digikam::AlbumManager::currentPAlbum | ( | ) | const |
Temporary fix, to return multiple items, iterate and cast each element
QList< TAlbum * > Digikam::AlbumManager::currentTAlbums | ( | ) | const |
bool Digikam::AlbumManager::deleteSAlbum | ( | SAlbum * | album | ) |
album | the album to delete |
bool Digikam::AlbumManager::deleteTAlbum | ( | TAlbum * | album, |
QString & | errMsg, | ||
QList< qlonglong > * | imageIds = nullptr |
||
) |
The tag is removed from the database
album | the TAlbum to delete |
errMsg | this will contain the error message describing why the |
imageIds | list of image ID from the database where tag is removed |
Album * Digikam::AlbumManager::findAlbum | ( | Album::Type | type, |
int | id | ||
) | const |
type | the type of album |
id | the id for the album (not the global id) |
Album * Digikam::AlbumManager::findAlbum | ( | int | gid | ) | const |
gid | the global id for the album |
DAlbum * Digikam::AlbumManager::findDAlbum | ( | int | id | ) | const |
AlbumList Digikam::AlbumManager::findOrCreateTAlbums | ( | const QStringList & | tagPaths | ) |
If no corresponding TAlbum exists, a new one will be created.
tagPaths | A list of tag paths |
PAlbum * Digikam::AlbumManager::findPAlbum | ( | const QUrl & | url | ) | const |
url
url | the url we need to check |
PAlbum * Digikam::AlbumManager::findPAlbum | ( | int | id | ) | const |
SAlbum * Digikam::AlbumManager::findSAlbum | ( | const QString & | name | ) | const |
name | the name of the search |
SAlbum * Digikam::AlbumManager::findSAlbum | ( | int | id | ) | const |
QList< SAlbum * > Digikam::AlbumManager::findSAlbumsBySearchType | ( | int | searchType | ) | const |
searchType | the type of the search |
TAlbum * Digikam::AlbumManager::findTAlbum | ( | const QString & | tagPath | ) | const |
tagPath | the tag path ("People/Friend/John") |
TAlbum * Digikam::AlbumManager::findTAlbum | ( | int | id | ) | const |
QMap< YearMonth, int > Digikam::AlbumManager::getDAlbumsCount | ( | ) | const |
QHash< int, int > Digikam::AlbumManager::getFaceCount | ( | ) | const |
qlonglong Digikam::AlbumManager::getItemFromAlbum | ( | Album *const | album, |
const QString & | fileName | ||
) |
album | The album in which we search the item. |
fileName | The name of the item file. |
QHash< int, int > Digikam::AlbumManager::getPAlbumsCount | ( | ) | const |
AlbumList Digikam::AlbumManager::getRecentlyAssignedTags | ( | bool | includeInternal = false | ) | const |
includeInternal | include internal tags in the returned list, or skip them |
QHash< int, int > Digikam::AlbumManager::getTAlbumsCount | ( | ) | const |
QHash< int, int > Digikam::AlbumManager::getUnconfirmedFaceCount | ( | ) | const |
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.
bool Digikam::AlbumManager::mergeTAlbum | ( | TAlbum * | album, |
TAlbum * | destAlbum, | ||
bool | dialog, | ||
QString & | errMsg | ||
) |
This updates the image tags in the database
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)
bool Digikam::AlbumManager::renamePAlbum | ( | PAlbum * | album, |
const QString & | newName, | ||
QString & | errMsg | ||
) |
This is equivalent to actually renaming the corresponding folder on the disk.
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 |
bool Digikam::AlbumManager::renameTAlbum | ( | TAlbum * | album, |
const QString & | name, | ||
QString & | errMsg | ||
) |
This updates the tag name in the database
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 |
void Digikam::AlbumManager::setCurrentAlbums | ( | const QList< Album * > & | albums | ) |
Filter out the null pointers
Sort is needed to identify selection correctly, ex AlbumHistory
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
|
signal |
Signals for deleting and adding will be sent afterwards, but the album object is guaranteed not to be deleted until after signalAlbumMoved.
|
signal |
For identification purposes, the former album pointer is passed.
|
signal |
After signalAlbumAboutToBeMoved, all four signals for first deleting and then adding will have been sent.
|
signal |
Please note that affected albums may appear or disappear after this signal has been emitted.
void Digikam::AlbumManager::startScan | ( | ) |
If the libraryPath has not changed since the last scan, then nothing happens
QHash< int, QString > Digikam::AlbumManager::tagNames | ( | bool | includeInternal = false | ) | const |
includeInternal | include internal tags in the returned list, or skip them |
QStringList Digikam::AlbumManager::tagNames | ( | const QList< int > & | tagIDs, |
bool | includeInternal = false |
||
) | const |
tagIDs | list of tag album IDs |
includeInternal | include internal tags in the returned list, or skip them |
QHash< int, QString > Digikam::AlbumManager::tagPaths | ( | bool | leadingSlash = true , |
bool | includeInternal = false |
||
) | const |
leadingSlash | if true return tags with a leading slash |
includeInternal | include internal tags in the returned list, or skip them |
QStringList Digikam::AlbumManager::tagPaths | ( | const QList< int > & | tagIDs, |
bool | leadingSlash = true , |
||
bool | includeInternal = false |
||
) | const |
tagIDs | list of tag album IDs |
leadingSlash | if true return tags with a leading slash |
includeInternal | include internal tags in the returned list, or skip them |
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
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 |
bool Digikam::AlbumManager::updateSAlbum | ( | SAlbum * | album, |
const QString & | changedQuery, | ||
const QString & | changedName = QString() , |
||
DatabaseSearch::Type | type = DatabaseSearch::UndefinedType |
||
) |
album | the album to update |
changedQuery | 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 |
bool Digikam::AlbumManager::updateTAlbumIcon | ( | TAlbum * | album, |
const QString & | iconKDE, | ||
qlonglong | iconID, | ||
QString & | errMsg | ||
) |
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 |