/* ============================================================ * * This file is a part of digiKam project * https://www.digikam.org * * Date : 2004-06-15 * Description : digiKam album types * * SPDX-FileCopyrightText: 2004-2005 by Renchi Raju * SPDX-FileCopyrightText: 2006-2026 by Gilles Caulier * SPDX-FileCopyrightText: 2014-2015 by Mohamed_Anwer * * SPDX-License-Identifier: GPL-2.0-or-later * * ============================================================ */ #pragma once // Qt includes #include #include #include #include #include #include // Local includes #include "coredbalbuminfo.h" #include "digikam_export.h" namespace Digikam { /** * Album list type definition. */ class Album; typedef QList AlbumList; class CoreDbUrl; /** * @class Album * @brief Abstract base class for all album types * * A class which provides an abstraction for a type Album. This class is meant to * be derived and every time a new Album Type is defined add a enum corresponding * to that to Album::Type * * This class provides a means of building a tree representation for * Albums @see Album::setParent(). */ class DIGIKAM_GUI_EXPORT Album { public: enum Type { PHYSICAL = 0, ///< A physical album type @see PAlbum TAG, ///< A tag album type @see TAlbum DATE, ///< A date album type @see DAlbum SEARCH, ///< A search album type @see SAlbum FACE ///< A faces album type @see FAlbum }; /** * @return the parent album for this album */ Album* parent() const; /** * @return the first child of this album or 0 if no children */ Album* firstChild() const; /** * @return the last child of this album or 0 if no children */ Album* lastChild() const; /** * @return the next sibling of this album of this album or 0 * if no next sibling * @see AlbumIterator */ Album* next() const; /** * @return the previous sibling of this album of this album or 0 if no * previous sibling * @see AlbumIterator */ Album* prev() const; /** * @return the child of this album at row */ Album* childAtRow(int row) const; /** * @return a list of all child Albums */ AlbumList childAlbums(bool recursive = false); /** * @return a list of all child Albums */ QList childAlbumIds(bool recursive = false); /** * @return the type of album * @see Type */ Type type() const; /** * Each album has a @p ID uniquely identifying it in the set of Albums of * a Type * * @note The @p ID for a root Album is always 0 * * @return the @p ID of the album * @see globalID() */ int id() const; /** * An album ID is only unique among the set of all Albums of its Type. * This is a global Identifier which will uniquely identifying the Album * among all Albums * * @note If you are adding a new Album Type make sure to update * this implementation. * * You can always get the @p ID of the album using something like * * @code * int albumID = rootAlbum->globalID() - album->globalID(); * @endcode * * @return the @p globalID of the album * @see id() */ int globalID() const; /** * @return the @p childCount of the album */ int childCount() const; /** * @return the @p rowFromAlbum of the album */ int rowFromAlbum() const; /** * @return the @p title aka name of the album */ QString title() const; /** * @return the kde url of the album */ virtual CoreDbUrl databaseUrl() const = 0; /** * @return true is the album is a Root Album */ bool isRoot() const; /** * @return true if the @p album is in the parent hierarchy * * @param album the album to check whether it belongs in the child * hierarchy */ bool isAncestorOf(const Album* const album) const; /** * @return true if the Album was created by Labels Tree * */ bool isUsedByLabelsTree() const; /** * @return true if the album was created to be a trash * virtual album */ bool isTrashAlbum() const; /** * This allows to associate some "extra" data to a Album. As one * Album can be used by several objects (often views) which all need * to add some data, you have to use a key to reference your extra data * within the Album. * * That way a Album can hold and provide access to all those views * separately. * * for eg, * * @code * album->setExtraData( this, searchFolderItem ); * @endcode * * and can later access the searchFolderItem by doing * * @code * SearchFolderItem *item = static_cast(album->extraData(this)); * @endcode * * Note: you have to remove and destroy the data you associated yourself * when you don't need it anymore! * * @param key the key of the extra data * @param value the value of the extra data * @see extraData * @see removeExtraData */ void setExtraData(const void* const key, void* const value); /** * Remove the associated extra data associated with @p key * * @param key the key of the extra data * @see setExtraData * @see extraData */ void removeExtraData(const void* const key); /** * Retrieve the associated extra data associated with @p key * * @param key the key of the extra data * @see setExtraData * @see extraData */ void* extraData(const void* const key) const; /** * Sets the property m_usedByLabelsTree to true if the search album * was created using the Colors and labels tree view * * @param isUsed => the status of the usage */ void setUsedByLabelsTree(bool isUsed); /** * @brief Produces the global id * @param type The type of the album * @param id the (type-specific) id of the album * @return the global id */ static int globalID(Type type, int id); /** * For secure deletion in an album model, * call this function beforehand */ void prepareForDeletion(); protected: /** * Constructor */ Album(Album::Type type, int id, bool root); /** * Destructor * * this will also recursively delete all child Albums */ virtual ~Album(); /** * Delete all child albums and also remove any associated extra data */ void clear(); /** * @internal use only * * Set a new title for the album * * @param title new title for the album */ void setTitle(const QString& title); /** * @internal use only * * Set the parent of the album * * @param parent set the parent album of album to @p parent */ void setParent(Album* const parent); /** * @internal use only * * Insert an Album as a child for this album * * @param child the Album to add as child */ void insertChild(Album* const child); /** * @internal use only * * Remove a Album from the children list for this album * * @param child the Album to remove */ void removeChild(Album* const child); private: /// @note disabled Album() = delete; Album& operator==(const Album&) = delete; Q_DISABLE_COPY(Album) private: mutable QReadWriteLock m_cacheLock; bool m_root = false; bool m_usedByLabelsTree = false; int m_id = -1; int m_row = 0; QString m_name; QString m_title; QMap m_extraMap; QList m_childCache; Type m_type = PHYSICAL; Album* m_parent = nullptr; friend class AlbumManager; }; /** * @class PAlbum * * A Physical Album representation */ class DIGIKAM_GUI_EXPORT PAlbum : public Album { public: /// Constructor for root album explicit PAlbum(const QString& title); /// Constructor for album root albums PAlbum(int albumRoot, const QString& label); /// Constructor for normal albums PAlbum(int albumRoot, const QString& parentPath, const QString& title, int id); /// Constructor for Trash album PAlbum(const QString& parentPath, int albumRoot); ~PAlbum() override = default; void setCaption(const QString& caption); void setCategory(const QString& category); void setDate(const QDate& date); QString albumRootPath() const; QString albumRootLabel() const; int albumRootId() const; QString caption() const; QString category() const; QDate date() const; QString albumPath() const; QString prettyUrl() const; QString folderPath() const; CoreDbUrl databaseUrl() const override; QUrl fileUrl() const; qlonglong iconId() const; bool isAlbumRoot() const; private: /** * A special integer for Trash virtual folders Ids; * That gets decremented not incremented */ static int m_uniqueTrashId; bool m_isAlbumRootAlbum = false; int m_albumRootId = -1; QString m_path; QString m_parentPath = QLatin1String("/"); QString m_category; QString m_caption; qlonglong m_iconId = 0; QDate m_date; friend class AlbumManager; }; /** * @class TAlbum * * A Tag Album representation */ class DIGIKAM_GUI_EXPORT TAlbum : public Album { public: TAlbum(const QString& title, int id, bool root = false); ~TAlbum() override = default; /** * @return The tag path, e.g. "/People/Friend/John" if leadingSlash is true, * "People/Friend/John" if leadingSlash if false. * The root TAlbum returns "/" resp. "". */ QString tagPath(bool leadingSlash = true) const; QString standardIconName() const; CoreDbUrl databaseUrl() const override; QString prettyUrl() const; QString icon() const; qlonglong iconId() const; QList tagIDs() const; bool isInternalTag() const; bool hasProperty(const QString& key) const; QString property(const QString& key) const; QMap properties() const; private: int m_pid = 0; QString m_icon; qlonglong m_iconId = 0; friend class AlbumManager; }; /** * @class DAlbum * * A Date Album representation */ class DIGIKAM_GUI_EXPORT DAlbum : public Album { public: enum Range { Month = 0, Year }; public: explicit DAlbum(const QDate& date, bool root = false, Range range = Month); ~DAlbum() override = default; QDate date() const; Range range() const; CoreDbUrl databaseUrl() const override; private: static int m_uniqueID; QDate m_date; Range m_range = Month; friend class AlbumManager; }; /** * @class SAlbum * * A Search Album representation */ class DIGIKAM_GUI_EXPORT SAlbum : public Album { public: SAlbum(const QString& title, int id, bool root = false); ~SAlbum() override = default; CoreDbUrl databaseUrl() const override; QString query() const; DatabaseSearch::Type searchType() const; bool isNormalSearch() const; bool isAdvancedSearch() const; bool isKeywordSearch() const; bool isTimelineSearch() const; bool isHaarSearch() const; bool isMapSearch() const; bool isDuplicatesSearch() const; /** * Indicates whether this album is a temporary search or not. * * @return true if this is a temporary search album, else false */ bool isTemporarySearch() const; QString displayTitle() const; /** * Returns the title of search albums that is used to mark them as a * temporary search that isn't saved officially yet and is only used for * viewing purposes. * * @param type the type of the search to get the temporary title for * @param haarType there are several haar searches, so that this search type * needs a special handling * @return string that identifies this album uniquely as an unsaved search */ static QString getTemporaryTitle(DatabaseSearch::Type type, DatabaseSearch::HaarSearchType haarType = DatabaseSearch::HaarImageSearch); /** * Returns the title for a temporary haar search depending on the sub-type * used for this search * * @param haarType type of the haar search to get the name for * @return string that identifies this album uniquely as an unsaved search */ static QString getTemporaryHaarTitle(DatabaseSearch::HaarSearchType haarType); private: void setSearch(DatabaseSearch::Type type, const QString& query); private: QString m_query; DatabaseSearch::Type m_searchType = DatabaseSearch::UndefinedType; friend class AlbumManager; }; /** * @class AlbumIterator * * Iterate over all children of this Album. * @note It will not include the specified album * * Example usage: * \code * AlbumIterator it(album); * while ( it.current() ) * { * qCDebug(DIGIKAM_GENERAL_LOG) << "Album: " << it.current()->title(); * ++it; * } * @endcode * * \warning Do not delete albums using this iterator. */ class DIGIKAM_GUI_EXPORT AlbumIterator { public: explicit AlbumIterator(Album* const album); ~AlbumIterator() = default; AlbumIterator& operator++(); Album* operator*(); Album* current() const; private: /// @note disabled AlbumIterator() = delete; Q_DISABLE_COPY(AlbumIterator) private: Album* m_current = nullptr; Album* m_root = nullptr; }; } // namespace Digikam Q_DECLARE_METATYPE(Digikam::Album*) Q_DECLARE_METATYPE(QList)