digiKam Developer Documentation: Digikam::CollectionManager Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Types | Signals | Public Member Functions | Static Public Member Functions | List of all members
Digikam::CollectionManager Class Reference
Inheritance diagram for Digikam::CollectionManager:

## Public Types
enum | LocationCheckResult { LocationInvalidCheck , LocationAllRight , LocationHasProblems , LocationNotAllowed }

## Signals
void | triggerUpdateVolumesList ()

## Public Member Functions
void | refresh ()
| Clears all locations and re-reads the lists of collection locations.
void | setWatchDisabled ()
| Disables the collection watch.

## Static Public Member Functions
static void | cleanUp ()
static CollectionManager * | instance ()

## Operations on Albums
class | Private
class | CoreDbWatch
class | CoreDbAccess
QStringList | allAvailableAlbumRootPaths ()
| Returns a list of the paths of all currently available root paths.
QString | albumRootPath (int id)
| Returns the album root path with the given id.
QString | albumRootLabel (int id)
| Returns the album root label with the given id.
QUrl | albumRoot (const QUrl &fileUrl)
| For a given path, the part of the path that forms the album root is returned, ending without a slash.
QString | albumRootPath (const QUrl &fileUrl)
QString | albumRootPath (const QString &filePath)
bool | isAlbumRoot (const QUrl &fileUrl)
| Returns true if the given path forms an album root.
bool | isAlbumRoot (const QString &filePath)
| The file path should not end with the directory slash.
QString | album (const QUrl &fileUrl)
| Returns the album part of the given file path, i.e.
QString | album (const QString &filePath)
QString | album (const CollectionLocation &location, const QUrl &fileUrl)
QString | album (const CollectionLocation &location, const QString &filePath)
QUrl | oneAlbumRoot ()
| Returns just one album root, out of the list of available location, the one that is most suitable to serve as a default, e.g.
QString | oneAlbumRootPath ()

## Operations on Collection Location
CollectionLocation | addLocation (const QUrl &fileUrl, const QString &label=QString())
| Add the given file system location as new collection location.
CollectionLocation | addNetworkLocation (const QUrl &fileUrl, const QString &label=QString())
CollectionLocation | refreshLocation (const CollectionLocation &location, int newType, const QStringList &pathList, const QString &label=QString())
LocationCheckResult | checkLocation (const QUrl &fileUrl, QList< CollectionLocation > &assumeDeleted, QString *message=nullptr, QString *suggestedMessageIconName=nullptr)
| Analyzes the given file path.
LocationCheckResult | checkNetworkLocation (const QUrl &fileUrl, QList< CollectionLocation > &assumeDeleted, QString *message=nullptr, QString *suggestedMessageIconName=nullptr)
void | removeLocation (const CollectionLocation &location)
| Removes the given location.
void | setLabel (const CollectionLocation &location, const QString &label)
| Sets the label of the given location.
void | changeType (const CollectionLocation &location, int type)
| Changes the CollectionLocation::Type of the given location.
QList< CollectionLocation > | checkHardWiredLocations ()
| Checks the locations of type HardWired.
void | migrationCandidates (const CollectionLocation &disappearedLocation, QString *const technicalDescription, QStringList *const candidateIdentifiers, QStringList *const candidateDescriptions)
| For a given disappeared location (retrieved from checkHardWiredLocations()) retrieve a user-presentable technical description (excluding the CollectionLocation's label) and a list of identifiers and corresponding user presentable strings of candidates to where the given location may have been moved.
void | migrateToVolume (const CollectionLocation &location, const QString &identifier)
| Migrates the existing collection to a new volume, identified by an internal identifier as returned by checkHardWiredLocations().
QList< CollectionLocation > | allLocations ()
| Returns a list of all CollectionLocations stored in the database.
QList< CollectionLocation > | allAvailableLocations ()
| Returns a list of all currently available CollectionLocations.
CollectionLocation | locationForAlbumRootId (int id)
| Returns the location for the given album root id.
CollectionLocation | locationForAlbumRoot (const QUrl &fileUrl)
| Returns the CollectionLocation that contains the given album root.
CollectionLocation | locationForAlbumRootPath (const QString &albumRootPath)
CollectionLocation | locationForUrl (const QUrl &fileUrl)
| Returns the CollectionLocation that contains the given path.
CollectionLocation | locationForPath (const QString &filePath)
void | locationStatusChanged (const CollectionLocation &location, int oldStatus)
| Emitted when the status of a collection location changed.
void | locationPropertiesChanged (const CollectionLocation &location)
| Emitted when the label of a collection location is changed.

## Member Enumeration Documentation

## ◆ LocationCheckResult

enum Digikam::CollectionManager::LocationCheckResult

Enumerator
LocationInvalidCheck | The check did not succeed, status unknown.
LocationAllRight | All right. The accompanying message may be empty.
LocationHasProblems | Location can be added, but the user should be aware of a problem.
LocationNotAllowed | Adding the location will fail (e.g. there is already a location for the path)

## Member Function Documentation

## ◆ addLocation()

CollectionLocation Digikam::CollectionManager::addLocation | ( | const QUrl & | fileUrl,
|  | const QString & | label = `QString()`
| ) |  |

Type and availability will be detected. On failure returns null. This would be the case if the given url is already contained in another collection location. You may pass an optional user-visible label that will be stored in the database. The label has no further meaning and can be freely chosen.

CollectionLocation objects returned are simple data containers. If the corresponding location is returned, the data is still safe to access, but does not represent anything. Therefore, do not store returned objects, but prefer to retrieve them freshly.

## ◆ album()

QString Digikam::CollectionManager::album | ( | const QUrl & | fileUrl | ) |

the album root path at the beginning is removed and the second part, starting with "/", ending without a slash, is returned. Example: "/media/fotos/Paris 2007" gives "/Paris 2007" Returns a null QString if the file path is not located in an album root. Returns "/" if the file path is an album root. Note that trailing slashes are removed in the return value, regardless if there was one or not. Note that you have to feed a path/url pointing to a directory. File names cannot be recognized as such by this method, and will be treated as a directory.

## ◆ albumRoot()

QUrl Digikam::CollectionManager::albumRoot | ( | const QUrl & | fileUrl | ) |

Example: "/media/fotos/Paris 2007" gives "/media/fotos". Only available (or hidden, but available) album roots are guaranteed to be found.

## ◆ albumRootLabel()

QString Digikam::CollectionManager::albumRootLabel | ( | int | id | ) |

Returns a null QString if the root path does not exist or is not available.

## ◆ albumRootPath()

QString Digikam::CollectionManager::albumRootPath | ( | int | id | ) |

Returns a null QString if the root path does not exist or is not available.

## ◆ checkHardWiredLocations()

QList< CollectionLocation > Digikam::CollectionManager::checkHardWiredLocations | ( |  | ) |

If one of these is not available currently, it is added to the list of disappeared locations. This case may happen if a file system is changed, a backup restored or other actions taken that change the UUID, although the data may still be available and mounted. If there are hard-wired volumes available which are candidates for a newly appeared volume (in fact those that do not contain any collections currently), they are added to the map, identifier -> i18n'ed user presentable description. The identifier can be used for changeVolume.

## ◆ checkLocation()

CollectionManager::LocationCheckResult Digikam::CollectionManager::checkLocation | ( | const QUrl & | fileUrl,
|  | QList< CollectionLocation > & | assumeDeleted,
|  | QString * | message = `nullptr`,
|  | QString * | suggestedMessageIconName = `nullptr`
| ) |  |

Creates an info message describing the result of identification or possible problems. The text is i18n'ed and can be presented to the user. The returned result enum describes the test result.

## ◆ isAlbumRoot() [1/2]

bool Digikam::CollectionManager::isAlbumRoot | ( | const QString & | filePath | ) |

Using CoreDbUrl's method is fine.

## ◆ isAlbumRoot() [2/2]

bool Digikam::CollectionManager::isAlbumRoot | ( | const QUrl & | fileUrl | ) |

It will return false if the path is a path below an album root, or if the path does not belong to an album root. Example: "/media/fotos/Paris 2007" is an album with album root "/media/fotos". "/media/fotos" returns true, "/media/fotos/Paris 2007" and "/media" return false. Only available (or hidden, but available) album roots are guaranteed to be found.

## ◆ locationForAlbumRoot()

CollectionLocation Digikam::CollectionManager::locationForAlbumRoot | ( | const QUrl & | fileUrl | ) |

The path must be an album root with isAlbumRoot() == true. Returns 0 if no collection location matches. Only available (or hidden, but available) locations are guaranteed to be found.

## ◆ locationForUrl()

CollectionLocation Digikam::CollectionManager::locationForUrl | ( | const QUrl & | fileUrl | ) |

Equivalent to calling locationForAlbumRoot(albumRoot(fileUrl)). Only available (or hidden, but available) locations are guaranteed to be found.

## ◆ locationStatusChanged

void Digikam::CollectionManager::locationStatusChanged | ( | const CollectionLocation & | location,
|  | int | oldStatus
| ) |  |
| signal

This means that the location became available, hidden or unavailable.

An added location will change its status after addition, from Null to Available, Hidden or Unavailable.

A removed location will change its status to Deleted during the removal; in this case, you shall not use the object passed with this signal with any method of CollectionManager.

The second signal argument is of type CollectionLocation::Status and describes the status before the state change occurred

## ◆ migrateToVolume()

void Digikam::CollectionManager::migrateToVolume | ( | const CollectionLocation & | location,
|  | const QString & | identifier
| ) |  |

Use this only to react to changes like those detailed for checkHardWiredLocations; the actual data pointed to shall be unchanged.

## ◆ oneAlbumRoot()

QUrl Digikam::CollectionManager::oneAlbumRoot | ( |  | ) |

to suggest as default place when the user wants to add files.

## ◆ refresh()

void Digikam::CollectionManager::refresh | ( |  | ) |

Enables the watch.

## ◆ removeLocation()

void Digikam::CollectionManager::removeLocation | ( | const CollectionLocation & | location | ) |

This means that all images contained on the location will be removed from the database, all tags will be lost.

## ◆ setWatchDisabled()

void Digikam::CollectionManager::setWatchDisabled | ( |  | ) |

It will be re-enabled as soon as refresh() is called or any other action triggered.