digiKam Developer Documentation: Digikam::ItemComments Class Reference

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

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Digikam::ItemComments Class Reference

## Public Types
enum | LanguageChoiceBehavior { ReturnMatchingLanguageOnly , ReturnMatchingOrDefaultLanguage , ReturnMatchingDefaultOrFirstLanguage }
| The ItemComments class shall provide short-lived objects that provide read/write access to the comments stored in the database. More...
enum | UniqueBehavior { UniquePerLanguage , UniquePerLanguageAndAuthor }

## Public Member Functions
| ItemComments ()
| Create a null ItemComments object.
| ItemComments (const CoreDbAccess &access, qlonglong imageid)
| Create a ItemComments object for the image with the specified id.
| ItemComments (const ItemComments &other)
| ItemComments (qlonglong imageid)
| Create a ItemComments object for the image with the specified id.
void | addComment (const QString &comment, const QString &language=QString(), const QString &author=QString(), const QDateTime &date=QDateTime(), DatabaseComment::Type type=DatabaseComment::Comment)
| Add a new comment to the list of normal image comments, specified with language and author.
void | addHeadline (const QString &headline, const QString &language=QString(), const QString &author=QString(), const QDateTime &date=QDateTime())
| Convenience method to add a comment of type Headline.
void | addTitle (const QString &title, const QString &language=QString(), const QString &author=QString(), const QDateTime &date=QDateTime())
| Convenience method to add a comment of type Headline.
void | apply ()
| Apply all changes.
void | apply (CoreDbAccess &access)
QString | author (int index) const
void | changeAuthor (int index, const QString &author)
void | changeComment (int index, const QString &comment)
| Access individual properties.
void | changeDate (int index, const QDateTime &date)
void | changeLanguage (int index, const QString &language)
void | changeType (int index, DatabaseComment::Type type)
QString | comment (int index) const
QString | commentForLanguage (const QString &languageCode, int *const index=nullptr, LanguageChoiceBehavior behavior=ReturnMatchingDefaultOrFirstLanguage) const
| Returns a comment for the specified language.
QDateTime | date (int index) const
QString | defaultComment (DatabaseComment::Type type=DatabaseComment::Comment) const
| This methods presents one of the comment strings of the available comment as the default value, when you just want to have one string.
QString | defaultComment (int *const index, Digikam::DatabaseComment::Type type=DatabaseComment::Comment) const
bool | isNull () const
QString | language (int index) const
| RFC 3066 notation, or "x-default".
int | numberOfComments () const
| Returns the number of comments available.
ItemComments & | operator= (const ItemComments &other)
void | remove (int index)
| Remove the entry referred to by index.
void | removeAll ()
| Remove all entries of all types: Comments, Headlines, Titles.
void | removeAll (DatabaseComment::Type type)
| Remove all entries of the given type.
void | removeAllComments ()
| Convenience method: remove all entries of type Comment.
void | replaceComments (const CaptionsMap &comments, DatabaseComment::Type type=DatabaseComment::Comment)
| Replaces all existing comments with the given set of comments and associated language.
void | replaceFrom (const ItemComments &source)
| Replaces all entries in this object with all entries from source.
void | setUniqueBehavior (UniqueBehavior behavior)
| Changes the behavior to unique comments per language, see the enum above for possible values.
CaptionsMap | toCaptionsMap (DatabaseComment::Type=DatabaseComment::Comment) const
| Returns all entries of the given type in a CaptionsMap container.
DatabaseComment::Type | type (int index) const
| Access individual properties.

## Protected Member Functions
void | addCommentDirectly (const QString &comment, const QString &language, const QString &author, DatabaseComment::Type type, const QDateTime &date)

## Protected Attributes
QSharedDataPointer< Private > | d

## Member Enumeration Documentation

## ◆ LanguageChoiceBehavior

enum Digikam::ItemComments::LanguageChoiceBehavior

It is a mere wrapper around the less convenient access methods in CoreDB. Database results are cached, but the object will not listen to database changes from other places.

Changes are applied to the database only after calling apply(), which you can call any time and which will in any case be called from the destructor.

Enumerator
ReturnMatchingLanguageOnly | Return only a comment if the language code (at least the language code, the country part may differ) is identical. Else returns a null QString.
ReturnMatchingOrDefaultLanguage | If no matching language as above is found, return the default language.
ReturnMatchingDefaultOrFirstLanguage | If no matching or default language is found, return the first comment. Returns a null string only if no comment is available.

## ◆ UniqueBehavior

enum Digikam::ItemComments::UniqueBehavior

Enumerator
UniquePerLanguage | Allow only one comment per language. Default setting.
UniquePerLanguageAndAuthor | Allow multiple comments per language, each with a different author.

## Constructor & Destructor Documentation

## ◆ ItemComments()

Digikam::ItemComments::ItemComments | ( | const CoreDbAccess & | access,
|  | qlonglong | imageid
| ) |  |

The existing CoreDbAccess object will be used to access the database.

## Member Function Documentation

## ◆ addComment()

void Digikam::ItemComments::addComment | ( | const QString & | comment,
|  | const QString & | language = `QString()`,
|  | const QString & | author = `QString()`,
|  | const QDateTime & | date = `QDateTime()`,
|  | DatabaseComment::Type | type = `DatabaseComment::Comment`
| ) |  |

Checking for unique comments is done as set by setUniqueBehavior. If you pass a null string as language, it will be translated to the language code designating the default language ("x-default"). If you just want to change the one comment of the image, call addComment(myComment);

## ◆ addHeadline()

void Digikam::ItemComments::addHeadline | ( | const QString & | headline,
|  | const QString & | language = `QString()`,
|  | const QString & | author = `QString()`,
|  | const QDateTime & | date = `QDateTime()`
| ) |  |

Calls addComment, see above for more info.

## ◆ addTitle()

void Digikam::ItemComments::addTitle | ( | const QString & | title,
|  | const QString & | language = `QString()`,
|  | const QString & | author = `QString()`,
|  | const QDateTime & | date = `QDateTime()`
| ) |  |

Calls addComment, see above for more info.

## ◆ apply()

void Digikam::ItemComments::apply | ( |  | ) |

Also called in destructor, so you typically do not need to call this.

## ◆ changeComment()

void Digikam::ItemComments::changeComment | ( | int | index,
|  | const QString & | comment
| ) |  |

Please ensure that the specified index is a valid index

## ◆ commentForLanguage()

QString Digikam::ItemComments::commentForLanguage | ( | const QString & | languageCode,
|  | int *const | index = `nullptr`,
|  | LanguageChoiceBehavior | behavior = `ReturnMatchingDefaultOrFirstLanguage`
| ) |  | const

Matching behavior can be specified. Optionally also returns the index with which you can access further information about the comment.

## ◆ defaultComment()

QString Digikam::ItemComments::defaultComment | ( | DatabaseComment::Type | type = `DatabaseComment::Comment` | ) | const

Optionally also returns the index with which you can access further information about the comment.

## ◆ replaceComments()

void Digikam::ItemComments::replaceComments | ( | const CaptionsMap & | comments,
|  | DatabaseComment::Type | type = `DatabaseComment::Comment`
| ) |  |

Optionally date and author can be specified in CaptionsMap container.

## ◆ setUniqueBehavior()

void Digikam::ItemComments::setUniqueBehavior | ( | UniqueBehavior | behavior | ) |

Default value is UniquePerLanguage. Note: This is not a property of the database, but only of this single ItemComments object,

## ◆ type()

DatabaseComment::Type Digikam::ItemComments::type | ( | int | index | ) | const

Please ensure that the specified index is a valid index