digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
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.
 
ItemCommentsoperator= (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

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

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