digiKam Developer Documentation: Digikam::TagsCache 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 | Friends | List of all members
Digikam::TagsCache Class Reference
Inheritance diagram for Digikam::TagsCache:

## Public Types
enum | HiddenTagsPolicy { NoHiddenTags , IncludeHiddenTags }
enum | LeadingSlashPolicy { NoLeadingSlash , IncludeLeadingSlash }

## Signals
void | tagAboutToBeDeleted (QString name)
void | tagAdded (int tagId)
| These signals are provided for convenience; for finer grained information use CoreDbWatch.
void | tagDeleted (int tagId)

## Public Member Functions
bool | canBeWrittenToMetadata (int tagId) const
| Returns if a tag shall be written to the metadata of a file.
int | colorLabelForTag (int tagId)
| Return color label id corresponding of internal tags ID.
int | colorLabelFromTags (const QList< int > &tagIds)
| From the given list of tags, returns the color label corresponding to the first encountered tag which is a color label tag.
QVector< int > | colorLabelTags ()
| Returns all color label tags, where index is the label id and value the tag id.
bool | containsPublicTags (const QList< int > &tagIds) const
| Returns true if the given list of tag ids contains at least one non-internal tag.
int | createTag (const QString &tagPathToCreate)
| Add the tag described by the given tag path, and all missing parent tags, to the database.
QList< int > | createTags (const QStringList &tagPaths)
int | getOrCreateInternalTag (const QString &tagName)
| For the given tag name (not path!), find the existing tag or creates a new internal tags under the usual tag path used for internal tags.
int | getOrCreateTag (const QString &tagPath)
| A combination of tagForPath and createTag: Finds ids for the given tagPaths.
QList< int > | getOrCreateTags (const QStringList &tagPaths)
int | getOrCreateTagWithProperty (const QString &tagPath, const QString &property, const QString &value=QString())
| Calls getOrCreateTag for the given path, and ensures that the tag has assigned the given property.
bool | hasProperty (int tagId, const QString &property, const QString &value=QString()) const
| Tests if the tag has the given property: a) just has the property.
bool | hasTag (int id) const
| Returns true if the tag for the given id exists.
bool | isInternalTag (int tagId) const
| Returns if a tag is to be regarded program-internal, that is, a technical implementation detail not visible to the user at any time.
int | parentTag (int id) const
| Returns the parent tag id, or 0 if a toplevel tag or tag does not exist.
QList< int > | parentTags (int id) const
| Returns the parent tag ids of the given tag, starting with the toplevel tag, ending with the direct parent tag.
int | pickLabelForTag (int tagId)
| Return pick label id corresponding of internal tags ID.
int | pickLabelFromTags (const QList< int > &tagIds)
| From the given list of tags, returns the pick label corresponding to the first encountered tag which is a pick label tag.
QVector< int > | pickLabelTags ()
| Returns all pick label tags, where index is the label id and value the tag id.
QMap< QString, QString > | properties (int tagId) const
| Returns a list or a map of the properties of the tag.
QString | propertyValue (int tagId, const QString &property) const
| Returns the value of the property.
QStringList | propertyValues (int tagId, const QString &property) const
QList< int > | publicTags (const QList< int > &tagIds) const
| From the given list of tag ids, filter out any internal tags and return only public tags.
QStringList | shortenedTagPaths (const QList< int > &ids, LeadingSlashPolicy slashPolicy=IncludeLeadingSlash, HiddenTagsPolicy hiddenTagsPolicy=IncludeHiddenTags) const
| Utility method.
QStringList | shortenedTagPaths (const QList< int > &ids, QList< int > *sortedIds, LeadingSlashPolicy slashPolicy=IncludeLeadingSlash, HiddenTagsPolicy hiddenTagsPolicy=IncludeHiddenTags) const
int | tagForColorLabel (int label)
| Return internal tags ID corresponding of color label id.
int | tagForName (const QString &tagName, int parentId=0) const
| Returns the id of the tag with the given name and parent tag.
int | tagForPath (const QString &path) const
| Returns the tag matched exactly by the given path.
int | tagForPickLabel (int label)
| Return internal tags ID corresponding of pick label id.
QString | tagName (int id) const
| Returns the name of the tag with the given id.
QStringList | tagNames (const QList< int > &ids, HiddenTagsPolicy hiddenTagsPolicy=IncludeHiddenTags) const
QString | tagPath (int id, LeadingSlashPolicy slashPolicy=IncludeLeadingSlash) const
| Returns the path of the tag with the given id.
QStringList | tagPaths (const QList< int > &ids, LeadingSlashPolicy slashPolicy=IncludeLeadingSlash, HiddenTagsPolicy hiddenTagsPolicy=IncludeHiddenTags) const
QList< int > | tagsContaining (const QString &fragment, Qt::CaseSensitivity caseSensitivity=Qt::CaseInsensitive, HiddenTagsPolicy hiddenTagsPolicy=NoHiddenTags)
| Returns a list of tag ids whose tag name (not path) starts with / contains the given fragment.
QList< int > | tagsForName (const QString &tagName, HiddenTagsPolicy hiddenTagsPolicy=NoHiddenTags) const
| Finds all tags with the given name.
QList< int > | tagsForPaths (const QStringList &tagPaths) const
QList< int > | tagsStartingWith (const QString &begin, Qt::CaseSensitivity caseSensitivity=Qt::CaseInsensitive, HiddenTagsPolicy hiddenTagsPolicy=NoHiddenTags)
QList< int > | tagsWithProperty (const QString &property, const QString &value=QString()) const
| Finds all tags with the given property.
QList< int > | tagsWithPropertyCached (const QString &property) const
| This method is equivalent to calling tagsWithProperty(property), but the immediate result will be cached for subsequent calls.

## Static Public Member Functions
static TagsCache * | instance ()
static QLatin1String | propertyNameDigikamInternalTag ()
static QLatin1String | propertyNameExcludedFromWriting ()
static QLatin1String | tagPathOfDigikamInternalTags (LeadingSlashPolicy slashPolicy=IncludeLeadingSlash)

## Friends
class | ChangingDB
class | CoreDbAccess

## Member Enumeration Documentation

## ◆ LeadingSlashPolicy

enum Digikam::TagsCache::LeadingSlashPolicy

Enumerator
NoLeadingSlash | Ex: "Places/Cities/Paris".
IncludeLeadingSlash | Ex: "/Places/Cities/Paris".

## Member Function Documentation

## ◆ canBeWrittenToMetadata()

bool Digikam::TagsCache::canBeWrittenToMetadata | ( | int | tagId | ) | const

Always returns false if the tag is a program-internal tag.

## ◆ colorLabelForTag()

int Digikam::TagsCache::colorLabelForTag | ( | int | tagId | ) |

see ColorLabel values from globals.h. Return -1 if not it's found.

## ◆ colorLabelFromTags()

int Digikam::TagsCache::colorLabelFromTags | ( | const QList< int > & | tagIds | ) |

Returns -1 if no tag in the list is a color label tag.

## ◆ createTag()

int Digikam::TagsCache::createTag | ( | const QString & | tagPathToCreate | ) |

Returns the tag id. Use this if you know that tag path does not exist. If you are unsure, use getOrCreateTag.

## ◆ getOrCreateTag()

int Digikam::TagsCache::getOrCreateTag | ( | const QString & | tagPath | ) |

If a tag does not exist yet and create is true, it will be created. Otherwise the id 0 is returned for this path.

## ◆ getOrCreateTagWithProperty()

int Digikam::TagsCache::getOrCreateTagWithProperty | ( | const QString & | tagPath,
|  | const QString & | property,
|  | const QString & | value = `QString()`
| ) |  |

If you pass a null string as value, then the value is not checked and not changed.

## ◆ hasProperty()

bool Digikam::TagsCache::hasProperty | ( | int | tagId,
|  | const QString & | property,
|  | const QString & | value = `QString()`
| ) |  | const

b) has the property with the given value (value not null).

## ◆ parentTags()

QList< int > Digikam::TagsCache::parentTags | ( | int | id | ) | const

If the tag is a toplevel tag or does not exist, an empty list is returned.

## ◆ pickLabelForTag()

int Digikam::TagsCache::pickLabelForTag | ( | int | tagId | ) |

see PickLabel values from globals.h. Return -1 if not it's found.

## ◆ pickLabelFromTags()

int Digikam::TagsCache::pickLabelFromTags | ( | const QList< int > & | tagIds | ) |

Returns -1 if no tag in the list is a pick label tag.

## ◆ properties()

QMap< QString, QString > Digikam::TagsCache::properties | ( | int | tagId | ) | const

Note: The list and map may be constructed for each call. Prefer hasProperty() and property().

## ◆ propertyValue()

QString Digikam::TagsCache::propertyValue | ( | int | tagId,
|  | const QString & | property
| ) |  | const

Returning a null string cannot distinguish between the property set with a null value, or the property not set. The first method returns any property, if multiple are set with the same key.

## ◆ shortenedTagPaths()

QStringList Digikam::TagsCache::shortenedTagPaths | ( | const QList< int > & | ids,
|  | LeadingSlashPolicy | slashPolicy = `IncludeLeadingSlash`,
|  | HiddenTagsPolicy | hiddenTagsPolicy = `IncludeHiddenTags`
| ) |  | const

Orders the given tag paths. If tags begin with the same path (parent tags), the relevant part is cut off in the second line. The second variant allows you to pass a list as return parameter. This list will contain, upon return, the tag id corresponding to each tag in the returned, sorted list of shortened paths.

## ◆ tagAdded

void Digikam::TagsCache::tagAdded | ( | int | tagId | ) |
| signal

Use a queued connection if you carry out longer operations from slots connected to these signals.

## ◆ tagForColorLabel()

int Digikam::TagsCache::tagForColorLabel | ( | int | label | ) |

see ColorLabel values from globals.h. Return 0 if not it's found.

## ◆ tagForName()

int Digikam::TagsCache::tagForName | ( | const QString & | tagName,
|  | int | parentId = `0`
| ) |  | const

If parentId is 0, the tag is a toplevel tag. Returns 0 if there is no such tag.

## ◆ tagForPath()

int Digikam::TagsCache::tagForPath | ( | const QString & | path | ) | const

The path can be given with or without leading slash. Returns 0 if there is no such tag, or if path is empty. If you want to create the tag if it does not yet exist, use getOrCreateTag.

## ◆ tagForPickLabel()

int Digikam::TagsCache::tagForPickLabel | ( | int | label | ) |

see PickLabel values from globals.h. Return 0 if not it's found.

## ◆ tagName()

QString Digikam::TagsCache::tagName | ( | int | id | ) | const

For the tag Places/Cities/Paris, this is Paris. If there is no tag for the given id a null string is returned.

## ◆ tagPath()

QString Digikam::TagsCache::tagPath | ( | int | id,
|  | LeadingSlashPolicy | slashPolicy = `IncludeLeadingSlash`
| ) |  | const

For the tag Places/Cities/Paris, this is Places/Cities/Paris. If there is no tag for the given id a null string is returned.

## ◆ tagsForName()

QList< int > Digikam::TagsCache::tagsForName | ( | const QString & | tagName,
|  | HiddenTagsPolicy | hiddenTagsPolicy = `NoHiddenTags`
| ) |  | const

For "Paris", this may give "Places/Cities/Paris" and "Places/USA/Texas/Paris". If there is no tag with the given name at all, returns an empty list.

## ◆ tagsWithProperty()

QList< int > Digikam::TagsCache::tagsWithProperty | ( | const QString & | property,
|  | const QString & | value = `QString()`
| ) |  | const

The tag: a) just has the property. b) has the property with the given value (value not null). Note: The returned list is sorted.

## ◆ tagsWithPropertyCached()

QList< int > Digikam::TagsCache::tagsWithPropertyCached | ( | const QString & | property | ) | const

Use it for queries for which you know that they will be issued very often, so that it's worth caching the result of the already pretty fast tagsWithProperty().