Debian Codegraph @

core/libs/album/treeview/abstractalbumtreeview.h

raw
1 /* ============================================================
2 *
3 * This file is a part of digiKam project
4 * https://www.digikam.org
5 *
6 * Date : 2009-03-25
7 * Description : Tree View for album models
8 *
9 * SPDX-FileCopyrightText: 2009-2010 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
10 * SPDX-FileCopyrightText: 2010-2011 by Andi Clemens <andi dot clemens at gmail dot com>
11 * SPDX-FileCopyrightText: 2009-2026 by Gilles Caulier <caulier dot gilles at gmail 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 <QTreeView>
22
23 // Local includes
24
25 #include "albummanager.h"
26 #include "albummodel.h"
27 #include "albumfiltermodel.h"
28 #include "albumpointer.h"
29 #include "statesavingobject.h"
30
31 namespace Digikam
32 {
33
34 class ContextMenuHelper;
35 class TagModificationHelper;
36
37 // NOTE: This structure name can be in conflict with QAbstractItemView::State. FIXME later.
38 struct State;
39
40 /**
41 * @brief Base class for all tree views that display Album-based content provided by an
42 * AbstractSpecificAlbumModel. This class enables various utility functions like
43 * selecting albums on mouse actions or providing an infrastructure for
44 * displaying a context menu for albums.
45 *
46 * Context menu handling is implemented as template methods with hook methods
47 * that can be implemented by subclasses to provide a custom behavior. In
48 * default mode no context menu is shown at all. It must be enabled via a call
49 * to setEnableContextMenu.
50 */
51 class AbstractAlbumTreeView : public QTreeView,
52 public StateSavingObject
53 {
54 Q_OBJECT
55
56 public:
57
58 enum Flag
59 {
60 /**
61 * Create a default model. Not supported by abstract classes.
62 * Not part of default flags!
63 */
64 CreateDefaultModel,
65
66 /**
67 * Create a default filter model.
68 */
69 CreateDefaultFilterModel,
70
71 /**
72 * Create a delegate which paints according to settings.
73 * If not set, the Qt default delegate of the view is used.
74 */
75 CreateDefaultDelegate,
76
77 /**
78 * Show the count according to the settings.
79 * If not set, call setShowCount() on the model yourself.
80 */
81 ShowCountAccordingToSettings,
82
83 /**
84 * Always show the inclusive counts.
85 * Not part of default flags!
86 */
87 AlwaysShowInclusiveCounts,
88
89 DefaultFlags = CreateDefaultFilterModel | CreateDefaultDelegate | ShowCountAccordingToSettings
90 };
91 Q_DECLARE_FLAGS(Flags, Flag)
92
93 public:
94
95 /**
96 * @brief Constructs an album tree view.
97 * If you give 0 for model, call setAlbumModel afterwards.
98 * If you supply 0 for filterModel, call setAlbumFilterModel afterwards.
99 */
100 AbstractAlbumTreeView(QWidget* const parent, Flags flags);
101 ~AbstractAlbumTreeView() override;
102
103 AbstractSpecificAlbumModel* albumModel() const;
104 AlbumFilterModel* albumFilterModel() const;
105
106 /**
107 * @brief Enable expanding of tree items on single click on the item (default: off)
108 */
109 void setExpandOnSingleClick(const bool doThat);
110
111 /**
112 * @brief Expand an item when making it the new current item
113 */
114 void setExpandNewCurrentItem(const bool doThat);
115
116 /**
117 * @brief Sets whether to select an album on click via the album manager or not.
118 *
119 * @param selectOnClick if true, a click on an item automatically sets this
120 * item as the current album in the album manager
121 */
122 void setSelectAlbumOnClick(const bool selectOnClick);
123
124 /**
125 * @brief Determines the global decision to show a popup menu or not. More detailed
126 * decision at which position a menu can be shown and where not can be made
127 * by implementing showContextMenuAt.
128 *
129 * @param enable if true, a context menu can be shown
130 */
131 void setEnableContextMenu(const bool enable);
132
133 /**
134 * @brief Sets whether to select the album under the mouse cursor on a context menu
135 * request (so that the album is shown using the album manager) or not
136 *
137 * Defaults to true.
138 *
139 * @param select true if a context menu request shall select the album
140 */
141 void setSelectOnContextMenu(const bool select);
142
143 /**
144 * @brief Set the context menu title and icon.
145 * This is used by the default implementation of contextMenuIcon()
146 * and contextMenuTitle(). You can alternatively reimplement these methods.
147 */
148 void setContextMenuIcon(const QPixmap& pixmap);
149 void setContextMenuTitle(const QString& title);
150
151 /**
152 * @brief This is a combination of indexAt() checked with visualRect().
153 * @param p must be in the viewport currently. Decoration will not be included.
154 * Suitable for mouse click positions.
155 */
156 QModelIndex indexVisuallyAt(const QPoint& p);
157
158 /**
159 * @brief Ensures that every current match is visible by expanding all parent
160 * entries.
161 *
162 * @param index the index to start ensuring expansion state
163 * @return <code>true</code> if there was a match under <code>index</code>.
164 * This return value can normally be ignored by the caller because
165 * it is only used for an internal recursion.
166 */
167 bool expandMatches(const QModelIndex& index);
168
169 //@{
170
171 /**
172 * @brief Implements state loading for the album tree view in a somewhat clumsy
173 * procedure because the model may not be fully loaded when this method is
174 * called. Therefore the config is first parsed into d->statesByAlbumId
175 * which holds the state of all tree view entries indexed by album id.
176 * Afterwards an initial sync run is done restoring the state of all model
177 * entries that are already present at this time. Every processed entry
178 * is removed from d->statesByAlbumId. If there are still entries left in
179 * this map we assume that the model is not fully loaded at the moment.
180 * Therefore the rowsInserted signal is connected to a slot that restores
181 * the state of new rows based on the remaining entries in
182 * d->statesByAlbumId.
183 */
184 void doLoadState() override;
185 void doSaveState() override;
186
187 //@}
188
189 /**
190 * @brief Some treeviews shall control the global current album kept by AlbumManager.
191 * Other treeview are self-contained and shall not change the current album.
192 * Default: false
193 */
194 void setAlbumManagerCurrentAlbum(const bool setCurrentAlbum);
195
196 /**
197 * @brief Add a context menu element which can add actions to the context
198 * menu when the menu is generated.
199 * First, addCustomContextMenuActions is called, then
200 * all elements' addActions method is called in order of addition.
201 */
202 class ContextMenuElement
203 {
204 public:
205
206 ContextMenuElement() = default;
207 virtual ~ContextMenuElement() = default;
208
209 /**
210 * @brief Add actions to the context menu being generated
211 *
212 * @param view The AbstractAlbumTreeView which generates the menu
213 * @param cmh helper object to create the context menu
214 * @param album the album on which the context menu will be created. May be null if
215 * it is requested on no tag entry
216 */
217 virtual void addActions(AbstractAlbumTreeView* view,
218 ContextMenuHelper& cmh,
219 Album* album) = 0;
220
221 private:
222
223 Q_DISABLE_COPY(ContextMenuElement)
224 };
225
226 void addContextMenuElement(ContextMenuElement* const element);
227 void removeContextMenuElement(ContextMenuElement* const element);
228 QList<ContextMenuElement*> contextMenuElements() const;
229
230 template<class A>
231 QList<A*> currentAlbums();
232
233 /**
234 * @brief For internal use only.
235 */
236 bool viewportEvent(QEvent* event) override;
237
238 /**
239 * @return selected Items
240 */
241 QList<Album*> selectedItems();
242
243 public Q_SLOTS:
244
245 void setSearchTextSettings(const SearchTextSettings& settings);
246
247 /**
248 * @brief Selects the given album.
249 *
250 * @param albums the albums to select
251 * @param selectInAlbumManager the album will be set as current album, if both
252 * this parameter is true and setAlbumManagerCurrentAlbum() was set to true.
253 */
254 void setCurrentAlbums(const QList<Album*>& albums, bool selectInAlbumManager = true);
255
256 /**
257 * @brief Adapt the column sizes to the contents of the tree view.
258 */
259 void adaptColumnsToContent();
260
261 /**
262 * @brief Scrolls to the first selected album if there is one.
263 */
264 void scrollToSelectedAlbum();
265
266 /**
267 * @brief Expands the complete tree under the given index.
268 *
269 * @param index the index to start expanding everything
270 */
271 void expandEverything(const QModelIndex& index);
272
273 /**
274 * @brief slotExpandNode - expands recursively selected nodes
275 */
276 void slotExpandNode();
277
278 /**
279 * @brief slotCollapseNode - collapse recursively selected nodes
280 */
281 void slotCollapseNode();
282
283 /**
284 * @brief slotCollapseAllNodes - collapse all nodes without root node
285 */
286 void slotCollapseAllNodes();
287
288 Q_SIGNALS:
289
290 /**
291 * @brief Emitted when the currently selected album changes
292 */
293 void currentAlbumChanged(Album* currentAlbum);
294
295 /**
296 * @brief Emitted when the current selection changes. Use currentChanged unless in multi-selection mode.
297 */
298 void selectedAlbumsChanged(const QList<Album*>& selectedAlbums);
299
300 protected Q_SLOTS:
301
302 /**
303 * @note override if implemented behavior is not as intended
304 */
305 virtual void slotRootAlbumAvailable();
306
307 void slotSearchTextSettingsChanged(bool wasSearching, bool searching);
308 void slotSearchTextSettingsAboutToChange(bool searched, bool willSearch);
309 void slotCurrentChanged();
310 void slotSelectionChanged();
311
312 void albumSettingsChanged();
313
314 protected:
315
316 //@{
317
318 // Context menu handling
319
320 /**
321 * @brief Hook method to implement that determines if a context menu shall be
322 * displayed for the given event at the position coded in the event.
323 *
324 * @param event context menu event to react on
325 * @param albumForEvent the album at the mouse position or null if there is
326 * no album at that position
327 * @return true if a context menu shall be displayed at the event
328 * coordinates, else false
329 */
330 virtual bool showContextMenuAt(QContextMenuEvent* event, Album* albumForEvent);
331
332 /**
333 * @brief Hook method that can be implemented to return a special icon used for the
334 * context menu.
335 *
336 * @return the icon for the context menu
337 */
338 virtual QPixmap contextMenuIcon() const;
339
340 /**
341 * @brief Hook method to implement that returns the title for the context menu.
342 *
343 * @return title for the context menu
344 */
345 virtual QString contextMenuTitle() const;
346
347 /**
348 * @brief Hook method to add custom actions to the generated context menu.
349 *
350 * @param cmh helper object to create the context menu
351 * @param album tag on which the context menu will be created. May be null if
352 * it is requested on no tag entry
353 */
354 virtual void addCustomContextMenuActions(ContextMenuHelper& cmh, Album* album);
355
356 /**
357 * @brief Hook method to handle the custom context menu actions that were added
358 * with addCustomContextMenuActions.
359 *
360 * @param action the action that was chosen by the user, may be null if none
361 * of the custom actions were selected
362 * @param album the tag on which the context menu was requested. May be null
363 * if there was no
364 */
365 virtual void handleCustomContextMenuAction(QAction* action,
366 const AlbumPointer<Album>& album);
367
368 //@}
369
370 //@{
371
372 /// Other helper methods.
373
374 void mousePressEvent(QMouseEvent* e) override;
375
376 void rowsInserted(const QModelIndex& index, int start, int end) override;
377 void rowsAboutToBeRemoved(const QModelIndex& parent, int start, int end) override;
378 void startDrag(Qt::DropActions supportedActions) override;
379 void dragEnterEvent(QDragEnterEvent* e) override;
380 void dragMoveEvent(QDragMoveEvent* e) override;
381 void dragLeaveEvent(QDragLeaveEvent* e) override;
382 void dropEvent(QDropEvent* e) override;
383
384 virtual void middleButtonPressed(Album* a);
385 virtual QPixmap pixmapForDrag(const QStyleOptionViewItem& option, QList<QModelIndex> indexes);
386
387 virtual void setAlbumFilterModel(AlbumFilterModel* const filterModel);
388 void setAlbumModel(AbstractSpecificAlbumModel* const model);
389
390 //@}
391
392 protected:
393
394 AbstractSpecificAlbumModel* m_albumModel = nullptr;
395 AlbumFilterModel* m_albumFilterModel = nullptr;
396 AlbumModelDragDropHandler* m_dragDropHandler = nullptr;
397
398 int m_lastScrollBarValue = 0;
399 bool m_checkOnMiddleClick = false;
400 bool m_restoreCheckState = false;
401 Flags m_flags = DefaultFlags;
402
403 private:
404
405 void saveStateRecursive(const QModelIndex& index,
406 QList<int>& selection, QList<int>& expansion);
407
408 /**
409 * @brief Restores the state of the index and all sub-indexes if there is an entry
410 * for this index in stateStore. Every album that is restored is removed
411 * from the stateStore.
412 *
413 * @param index the index to start restoring
414 * @param stateStore states indexed by album id
415 */
416 void restoreStateForHierarchy(const QModelIndex& index,
417 const QMap<int, Digikam::State>& stateStore);
418
419 /**
420 * @brief Restore the state for this index.
421 */
422 void restoreState(const QModelIndex& index,
423 const QMap<int, Digikam::State>& stateStore);
424
425 /**
426 * @brief Creates the context menu.
427 *
428 * @param event the event that requested the menu
429 */
430 void contextMenuEvent(QContextMenuEvent* event) override;
431
432 private Q_SLOTS:
433
434 /**
435 * @brief Adapts the columns in between the given model indices to the content
436 * size. This can be connected to dataChanged.
437 *
438 * @param topLeft top left index of changed data
439 * @param bottomRight index of changed data
440 */
441 void adaptColumnsOnDataChange(const QModelIndex& topLeft, const QModelIndex& bottomRight);
442
443 /**
444 * @brief Adapt the column sizes to new contents. This can be connected to all
445 * signals indicating row changes.
446 *
447 * @param parent the parent index of changed rows
448 * @param start the start row changed under the parent
449 * @param end the end row changed under the parent
450 */
451 void adaptColumnsOnRowChange(const QModelIndex& parent, int start, int end);
452
453 /**
454 * @brief Adapts the column sizes if the layout changes.
455 */
456 void adaptColumnsOnLayoutChange();
457
458 /**
459 * @brief This slot is used to ensure that after searching for entries the correct
460 * album is selected again. Therefore it tracks new selections.
461 */
462 void currentAlbumChangedForBackupSelection(Album* currentAlbum);
463
464 /**
465 * @note This slots is used to fix bug 400960.
466 */
467 void slotScrollBarValueChanged(int value);
468 void slotScrollBarActionTriggered(int action);
469
470 private:
471
472 class Private;
473 Private* const d = nullptr;
474 };
475
476 } // namespace Digikam
477
478 Q_DECLARE_OPERATORS_FOR_FLAGS(Digikam::AbstractAlbumTreeView::Flags)