digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
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 TagsCacheinstance ()
 
static QLatin1String propertyNameDigikamInternalTag ()
 
static QLatin1String propertyNameExcludedFromWriting ()
 
static QLatin1String tagPathOfDigikamInternalTags (LeadingSlashPolicy slashPolicy=IncludeLeadingSlash)
 

Friends

class ChangingDB
 
class CoreDbAccess
 
class TagsCacheCreator
 

Member Enumeration Documentation

◆ 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().