Debian Codegraph @

core/libs/album/engine/album.h

raw
1 /* ============================================================
2 *
3 * This file is a part of digiKam project
4 * https://www.digikam.org
5 *
6 * Date : 2004-06-15
7 * Description : digiKam album types
8 *
9 * SPDX-FileCopyrightText: 2004-2005 by Renchi Raju <renchi dot raju at gmail dot com>
10 * SPDX-FileCopyrightText: 2006-2026 by Gilles Caulier <caulier dot gilles at gmail dot com>
11 * SPDX-FileCopyrightText: 2014-2015 by Mohamed_Anwer <m_dot_anwer at gmx dot com>
12 *
13 * SPDX-License-Identifier: GPL-2.0-or-later
14 *
15 * ============================================================ */
16
17 #pragma once
18
19 // Qt includes
20
21 #include <QMap>
22 #include <QUrl>
23 #include <QList>
24 #include <QString>
25 #include <QMetaType>
26 #include <QReadWriteLock>
27
28 // Local includes
29
30 #include "coredbalbuminfo.h"
31 #include "digikam_export.h"
32
33 namespace Digikam
34 {
35
36 /**
37 * Album list type definition.
38 */
39 class Album;
40 typedef QList<Album*> AlbumList;
41
42 class CoreDbUrl;
43
44 /**
45 * @class Album
46 * @brief Abstract base class for all album types
47 *
48 * A class which provides an abstraction for a type Album. This class is meant to
49 * be derived and every time a new Album Type is defined add a enum corresponding
50 * to that to Album::Type
51 *
52 * This class provides a means of building a tree representation for
53 * Albums @see Album::setParent().
54 */
55 class DIGIKAM_GUI_EXPORT Album
56 {
57 public:
58
59 enum Type
60 {
61 PHYSICAL = 0, ///< A physical album type @see PAlbum
62 TAG, ///< A tag album type @see TAlbum
63 DATE, ///< A date album type @see DAlbum
64 SEARCH, ///< A search album type @see SAlbum
65 FACE ///< A faces album type @see FAlbum
66 };
67
68 /**
69 * @return the parent album for this album
70 */
71 Album* parent() const;
72
73 /**
74 * @return the first child of this album or 0 if no children
75 */
76 Album* firstChild() const;
77
78 /**
79 * @return the last child of this album or 0 if no children
80 */
81 Album* lastChild() const;
82
83 /**
84 * @return the next sibling of this album of this album or 0
85 * if no next sibling
86 * @see AlbumIterator
87 */
88 Album* next() const;
89
90 /**
91 * @return the previous sibling of this album of this album or 0 if no
92 * previous sibling
93 * @see AlbumIterator
94 */
95 Album* prev() const;
96
97 /**
98 * @return the child of this album at row
99 */
100 Album* childAtRow(int row) const;
101
102 /**
103 * @return a list of all child Albums
104 */
105 AlbumList childAlbums(bool recursive = false);
106
107 /**
108 * @return a list of all child Albums
109 */
110 QList<int> childAlbumIds(bool recursive = false);
111
112 /**
113 * @return the type of album
114 * @see Type
115 */
116 Type type() const;
117
118 /**
119 * Each album has a @p ID uniquely identifying it in the set of Albums of
120 * a Type
121 *
122 * @note The @p ID for a root Album is always 0
123 *
124 * @return the @p ID of the album
125 * @see globalID()
126 */
127 int id() const;
128
129 /**
130 * An album ID is only unique among the set of all Albums of its Type.
131 * This is a global Identifier which will uniquely identifying the Album
132 * among all Albums
133 *
134 * @note If you are adding a new Album Type make sure to update
135 * this implementation.
136 *
137 * You can always get the @p ID of the album using something like
138 *
139 * @code
140 * int albumID = rootAlbum->globalID() - album->globalID();
141 * @endcode
142 *
143 * @return the @p globalID of the album
144 * @see id()
145 */
146 int globalID() const;
147
148 /**
149 * @return the @p childCount of the album
150 */
151 int childCount() const;
152
153 /**
154 * @return the @p rowFromAlbum of the album
155 */
156 int rowFromAlbum() const;
157
158 /**
159 * @return the @p title aka name of the album
160 */
161 QString title() const;
162
163 /**
164 * @return the kde url of the album
165 */
166 virtual CoreDbUrl databaseUrl() const = 0;
167
168 /**
169 * @return true is the album is a Root Album
170 */
171 bool isRoot() const;
172
173 /**
174 * @return true if the @p album is in the parent hierarchy
175 *
176 * @param album the album to check whether it belongs in the child
177 * hierarchy
178 */
179 bool isAncestorOf(const Album* const album) const;
180
181 /**
182 * @return true if the Album was created by Labels Tree
183 *
184 */
185 bool isUsedByLabelsTree() const;
186
187 /**
188 * @return true if the album was created to be a trash
189 * virtual album
190 */
191 bool isTrashAlbum() const;
192
193 /**
194 * This allows to associate some "extra" data to a Album. As one
195 * Album can be used by several objects (often views) which all need
196 * to add some data, you have to use a key to reference your extra data
197 * within the Album.
198 *
199 * That way a Album can hold and provide access to all those views
200 * separately.
201 *
202 * for eg,
203 *
204 * @code
205 * album->setExtraData( this, searchFolderItem );
206 * @endcode
207 *
208 * and can later access the searchFolderItem by doing
209 *
210 * @code
211 * SearchFolderItem *item = static_cast<SearchFolderItem*>(album->extraData(this));
212 * @endcode
213 *
214 * Note: you have to remove and destroy the data you associated yourself
215 * when you don't need it anymore!
216 *
217 * @param key the key of the extra data
218 * @param value the value of the extra data
219 * @see extraData
220 * @see removeExtraData
221 */
222 void setExtraData(const void* const key, void* const value);
223
224 /**
225 * Remove the associated extra data associated with @p key
226 *
227 * @param key the key of the extra data
228 * @see setExtraData
229 * @see extraData
230 */
231 void removeExtraData(const void* const key);
232
233 /**
234 * Retrieve the associated extra data associated with @p key
235 *
236 * @param key the key of the extra data
237 * @see setExtraData
238 * @see extraData
239 */
240 void* extraData(const void* const key) const;
241
242 /**
243 * Sets the property m_usedByLabelsTree to true if the search album
244 * was created using the Colors and labels tree view
245 *
246 * @param isUsed => the status of the usage
247 */
248 void setUsedByLabelsTree(bool isUsed);
249
250 /**
251 * @brief Produces the global id
252 * @param type The type of the album
253 * @param id the (type-specific) id of the album
254 * @return the global id
255 */
256 static int globalID(Type type, int id);
257
258 /**
259 * For secure deletion in an album model,
260 * call this function beforehand
261 */
262 void prepareForDeletion();
263
264 protected:
265
266 /**
267 * Constructor
268 */
269 Album(Album::Type type, int id, bool root);
270
271 /**
272 * Destructor
273 *
274 * this will also recursively delete all child Albums
275 */
276 virtual ~Album();
277
278 /**
279 * Delete all child albums and also remove any associated extra data
280 */
281 void clear();
282
283 /**
284 * @internal use only
285 *
286 * Set a new title for the album
287 *
288 * @param title new title for the album
289 */
290 void setTitle(const QString& title);
291
292 /**
293 * @internal use only
294 *
295 * Set the parent of the album
296 *
297 * @param parent set the parent album of album to @p parent
298 */
299 void setParent(Album* const parent);
300
301 /**
302 * @internal use only
303 *
304 * Insert an Album as a child for this album
305 *
306 * @param child the Album to add as child
307 */
308 void insertChild(Album* const child);
309
310 /**
311 * @internal use only
312 *
313 * Remove a Album from the children list for this album
314 *
315 * @param child the Album to remove
316 */
317 void removeChild(Album* const child);
318
319 private:
320
321 /// @note disabled
322 Album() = delete;
323 Album& operator==(const Album&) = delete;
324
325 Q_DISABLE_COPY(Album)
326
327 private:
328
329 mutable QReadWriteLock m_cacheLock;
330
331 bool m_root = false;
332 bool m_usedByLabelsTree = false;
333
334 int m_id = -1;
335 int m_row = 0;
336
337 QString m_name;
338 QString m_title;
339
340 QMap<const void*, void*> m_extraMap;
341
342 QList<Album*> m_childCache;
343
344 Type m_type = PHYSICAL;
345
346 Album* m_parent = nullptr;
347
348 friend class AlbumManager;
349 };
350
351 /**
352 * @class PAlbum
353 *
354 * A Physical Album representation
355 */
356 class DIGIKAM_GUI_EXPORT PAlbum : public Album
357 {
358 public:
359
360 /// Constructor for root album
361 explicit PAlbum(const QString& title);
362
363 /// Constructor for album root albums
364 PAlbum(int albumRoot, const QString& label);
365
366 /// Constructor for normal albums
367 PAlbum(int albumRoot, const QString& parentPath, const QString& title, int id);
368
369 /// Constructor for Trash album
370 PAlbum(const QString& parentPath, int albumRoot);
371 ~PAlbum() override = default;
372
373 void setCaption(const QString& caption);
374 void setCategory(const QString& category);
375 void setDate(const QDate& date);
376
377 QString albumRootPath() const;
378 QString albumRootLabel() const;
379 int albumRootId() const;
380 QString caption() const;
381 QString category() const;
382 QDate date() const;
383 QString albumPath() const;
384 QString prettyUrl() const;
385 QString folderPath() const;
386 CoreDbUrl databaseUrl() const override;
387 QUrl fileUrl() const;
388 qlonglong iconId() const;
389 bool isAlbumRoot() const;
390
391 private:
392
393 /**
394 * A special integer for Trash virtual folders Ids;
395 * That gets decremented not incremented
396 */
397 static int m_uniqueTrashId;
398
399 bool m_isAlbumRootAlbum = false;
400
401 int m_albumRootId = -1;
402
403 QString m_path;
404 QString m_parentPath = QLatin1String("/");
405
406 QString m_category;
407 QString m_caption;
408 qlonglong m_iconId = 0;
409
410 QDate m_date;
411
412 friend class AlbumManager;
413 };
414
415 /**
416 * @class TAlbum
417 *
418 * A Tag Album representation
419 */
420 class DIGIKAM_GUI_EXPORT TAlbum : public Album
421 {
422 public:
423
424 TAlbum(const QString& title, int id, bool root = false);
425 ~TAlbum() override = default;
426
427 /**
428 * @return The tag path, e.g. "/People/Friend/John" if leadingSlash is true,
429 * "People/Friend/John" if leadingSlash if false.
430 * The root TAlbum returns "/" resp. "".
431 */
432 QString tagPath(bool leadingSlash = true) const;
433 QString standardIconName() const;
434 CoreDbUrl databaseUrl() const override;
435 QString prettyUrl() const;
436 QString icon() const;
437 qlonglong iconId() const;
438 QList<int> tagIDs() const;
439
440 bool isInternalTag() const;
441 bool hasProperty(const QString& key) const;
442 QString property(const QString& key) const;
443 QMap<QString, QString> properties() const;
444
445 private:
446
447 int m_pid = 0;
448
449 QString m_icon;
450 qlonglong m_iconId = 0;
451
452 friend class AlbumManager;
453 };
454
455 /**
456 * @class DAlbum
457 *
458 * A Date Album representation
459 */
460 class DIGIKAM_GUI_EXPORT DAlbum : public Album
461 {
462 public:
463
464 enum Range
465 {
466 Month = 0,
467 Year
468 };
469
470 public:
471
472 explicit DAlbum(const QDate& date, bool root = false, Range range = Month);
473 ~DAlbum() override = default;
474
475 QDate date() const;
476 Range range() const;
477 CoreDbUrl databaseUrl() const override;
478
479 private:
480
481 static int m_uniqueID;
482 QDate m_date;
483 Range m_range = Month;
484
485 friend class AlbumManager;
486 };
487
488 /**
489 * @class SAlbum
490 *
491 * A Search Album representation
492 */
493 class DIGIKAM_GUI_EXPORT SAlbum : public Album
494 {
495 public:
496
497 SAlbum(const QString& title, int id, bool root = false);
498 ~SAlbum() override = default;
499
500 CoreDbUrl databaseUrl() const override;
501 QString query() const;
502 DatabaseSearch::Type searchType() const;
503 bool isNormalSearch() const;
504 bool isAdvancedSearch() const;
505 bool isKeywordSearch() const;
506 bool isTimelineSearch() const;
507 bool isHaarSearch() const;
508 bool isMapSearch() const;
509 bool isDuplicatesSearch() const;
510
511 /**
512 * Indicates whether this album is a temporary search or not.
513 *
514 * @return true if this is a temporary search album, else false
515 */
516 bool isTemporarySearch() const;
517
518 QString displayTitle() const;
519
520 /**
521 * Returns the title of search albums that is used to mark them as a
522 * temporary search that isn't saved officially yet and is only used for
523 * viewing purposes.
524 *
525 * @param type the type of the search to get the temporary title for
526 * @param haarType there are several haar searches, so that this search type
527 * needs a special handling
528 * @return string that identifies this album uniquely as an unsaved search
529 */
530 static QString getTemporaryTitle(DatabaseSearch::Type type,
531 DatabaseSearch::HaarSearchType haarType = DatabaseSearch::HaarImageSearch);
532
533 /**
534 * Returns the title for a temporary haar search depending on the sub-type
535 * used for this search
536 *
537 * @param haarType type of the haar search to get the name for
538 * @return string that identifies this album uniquely as an unsaved search
539 */
540 static QString getTemporaryHaarTitle(DatabaseSearch::HaarSearchType haarType);
541
542 private:
543
544 void setSearch(DatabaseSearch::Type type, const QString& query);
545
546 private:
547
548 QString m_query;
549 DatabaseSearch::Type m_searchType = DatabaseSearch::UndefinedType;
550
551 friend class AlbumManager;
552 };
553
554 /**
555 * @class AlbumIterator
556 *
557 * Iterate over all children of this Album.
558 * @note It will not include the specified album
559 *
560 * Example usage:
561 * \code
562 * AlbumIterator it(album);
563 * while ( it.current() )
564 * {
565 * qCDebug(DIGIKAM_GENERAL_LOG) << "Album: " << it.current()->title();
566 * ++it;
567 * }
568 * @endcode
569 *
570 * \warning Do not delete albums using this iterator.
571 */
572 class DIGIKAM_GUI_EXPORT AlbumIterator
573 {
574 public:
575
576 explicit AlbumIterator(Album* const album);
577 ~AlbumIterator() = default;
578
579 AlbumIterator& operator++();
580 Album* operator*();
581 Album* current() const;
582
583 private:
584
585 /// @note disabled
586 AlbumIterator() = delete;
587
588 Q_DISABLE_COPY(AlbumIterator)
589
590 private:
591
592 Album* m_current = nullptr;
593 Album* m_root = nullptr;
594 };
595
596 } // namespace Digikam
597
598 Q_DECLARE_METATYPE(Digikam::Album*)
599 Q_DECLARE_METATYPE(QList<Digikam::TAlbum*>)