digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
Digikam::AbstractAlbumTreeView Class Reference

Base class for all tree views that display Album-based content provided by an AbstractSpecificAlbumModel. More...

+ Inheritance diagram for Digikam::AbstractAlbumTreeView:

Classes

class  ContextMenuElement
 Add a context menu element which can add actions to the context menu when the menu is generated. More...
 

Public Types

enum  Flag {
  CreateDefaultModel , CreateDefaultFilterModel , CreateDefaultDelegate , ShowCountAccordingToSettings ,
  AlwaysShowInclusiveCounts , DefaultFlags = CreateDefaultFilterModel | CreateDefaultDelegate | ShowCountAccordingToSettings
}
 
typedef QFlags< FlagFlags
 
- Public Types inherited from Digikam::StateSavingObject
enum  StateSavingDepth { INSTANCE , DIRECT_CHILDREN , RECURSIVE }
 This enum defines the "depth" of the StateSavingObject::loadState() and StateSavingObject::saveState() methods. More...
 

Public Slots

void adaptColumnsToContent ()
 Adapt the column sizes to the contents of the tree view.
 
void expandEverything (const QModelIndex &index)
 Expands the complete tree under the given index.
 
void scrollToSelectedAlbum ()
 Scrolls to the first selected album if there is one.
 
virtual void setCurrentAlbums (const QList< Album * > &albums, bool selectInAlbumManager=true)
 Selects the given album.
 
void setSearchTextSettings (const SearchTextSettings &settings)
 
void slotCollapseAllNodes ()
 slotCollapseAllNodes - collapse all nodes without root node
 
void slotCollapseNode ()
 slotCollapseNode - collapse recursively selected nodes
 
void slotExpandNode ()
 slotExpandNode - expands recursively selected nodes
 

Signals

void currentAlbumChanged (Album *currentAlbum)
 Emitted when the currently selected album changes.
 
void selectedAlbumsChanged (const QList< Album * > &selectedAlbums)
 Emitted when the current selection changes.
 

Public Member Functions

 AbstractAlbumTreeView (QWidget *const parent, Flags flags)
 Constructs an album tree view.
 
void addContextMenuElement (ContextMenuElement *const element)
 
AlbumFilterModelalbumFilterModel () const
 
AbstractSpecificAlbumModelalbumModel () const
 
QList< ContextMenuElement * > contextMenuElements () const
 
template<class A >
QList< A * > currentAlbums ()
 
void doLoadState () override
 Implements state loading for the album tree view in a somewhat clumsy procedure because the model may not be fully loaded when this method is called.
 
void doSaveState () override
 Implement this hook method for state saving.
 
bool expandMatches (const QModelIndex &index)
 Ensures that every current match is visible by expanding all parent entries.
 
QModelIndex indexVisuallyAt (const QPoint &p)
 This is a combination of indexAt() checked with visualRect().
 
void removeContextMenuElement (ContextMenuElement *const element)
 
QList< Album * > selectedItems ()
 
void setAlbumManagerCurrentAlbum (const bool setCurrentAlbum)
 Some treeviews shall control the global current album kept by AlbumManager.
 
void setContextMenuIcon (const QPixmap &pixmap)
 Set the context menu title and icon.
 
void setContextMenuTitle (const QString &title)
 
void setEnableContextMenu (const bool enable)
 Determines the global decision to show a popup menu or not.
 
void setExpandNewCurrentItem (const bool doThat)
 Expand an item when making it the new current item.
 
void setExpandOnSingleClick (const bool doThat)
 Enable expanding of tree items on single click on the item (default: off)
 
void setSelectAlbumOnClick (const bool selectOnClick)
 Sets whether to select an album on click via the album manager or not.
 
void setSelectOnContextMenu (const bool select)
 Sets whether to select the album under the mouse cursor on a context menu request (so that the album is shown using the album manager) or not.
 
bool viewportEvent (QEvent *event) override
 For internal use only.
 
- Public Member Functions inherited from Digikam::StateSavingObject
 StateSavingObject (QObject *const host)
 Constructor.
 
virtual ~StateSavingObject ()
 Destructor.
 
StateSavingDepth getStateSavingDepth () const
 Returns the depth used for state saving or loading.
 
void loadState ()
 Invokes loading the class' state.
 
void saveState ()
 Invokes saving the class' state.
 
virtual void setConfigGroup (const KConfigGroup &group)
 Sets a dedicated config group that will be used to store and reload the state from.
 
virtual void setEntryPrefix (const QString &prefix)
 Define a prefix that will be used for every entry in the config group.
 
void setStateSavingDepth (const StateSavingDepth depth)
 Sets the depth used for state saving or loading.
 

Protected Slots

void albumSettingsChanged ()
 
void slotCurrentChanged ()
 
virtual void slotRootAlbumAvailable ()
 
void slotSearchTextSettingsAboutToChange (bool searched, bool willSearch)
 
void slotSearchTextSettingsChanged (bool wasSearching, bool searching)
 
void slotSelectionChanged ()
 

Protected Member Functions

virtual void addCustomContextMenuActions (ContextMenuHelper &cmh, Album *album)
 Hook method to add custom actions to the generated context menu.
 
virtual QPixmap contextMenuIcon () const
 Hook method that can be implemented to return a special icon used for the context menu.
 
virtual QString contextMenuTitle () const
 Hook method to implement that returns the title for the context menu.
 
void dragEnterEvent (QDragEnterEvent *e) override
 
void dragLeaveEvent (QDragLeaveEvent *e) override
 
void dragMoveEvent (QDragMoveEvent *e) override
 
void dropEvent (QDropEvent *e) override
 
virtual void handleCustomContextMenuAction (QAction *action, const AlbumPointer< Album > &album)
 Hook method to handle the custom context menu actions that were added with addCustomContextMenuActions.
 
virtual void middleButtonPressed (Album *a)
 
void mousePressEvent (QMouseEvent *e) override
 Other helper methods.
 
virtual QPixmap pixmapForDrag (const QStyleOptionViewItem &option, QList< QModelIndex > indexes)
 
void rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end) override
 
void rowsInserted (const QModelIndex &index, int start, int end) override
 
virtual void setAlbumFilterModel (AlbumFilterModel *const filterModel)
 
void setAlbumModel (AbstractSpecificAlbumModel *const model)
 
virtual bool showContextMenuAt (QContextMenuEvent *event, Album *albumForEvent)
 Hook method to implement that determines if a context menu shall be displayed for the given event at the position coded in the event.
 
void startDrag (Qt::DropActions supportedActions) override
 
- Protected Member Functions inherited from Digikam::StateSavingObject
QString entryName (const QString &base) const
 Always use this method to create config group entry names.
 
KConfigGroup getConfigGroup () const
 Returns the config group that must be used for state saving and loading.
 

Protected Attributes

AlbumFilterModelm_albumFilterModel = nullptr
 
AbstractSpecificAlbumModelm_albumModel = nullptr
 
bool m_checkOnMiddleClick = false
 
AlbumModelDragDropHandlerm_dragDropHandler = nullptr
 
Flags m_flags = DefaultFlags
 
int m_lastScrollBarValue = 0
 
bool m_restoreCheckState = false
 

Detailed Description

This class enables various utility functions like selecting albums on mouse actions or providing an infrastructure for displaying a context menu for albums.

Context menu handling is implemented as template methods with hook methods that can be implemented by subclasses to provide a custom behavior. In default mode no context menu is shown at all. It must be enabled via a call to setEnableContextMenu.

Member Enumeration Documentation

◆ Flag

Enumerator
CreateDefaultModel 

Create a default model.

Not supported by abstract classes. Not part of default flags!

CreateDefaultFilterModel 

Create a default filter model.

CreateDefaultDelegate 

Create a delegate which paints according to settings.

If not set, the Qt default delegate of the view is used.

ShowCountAccordingToSettings 

Show the count according to the settings.

If not set, call setShowCount() on the model yourself.

AlwaysShowInclusiveCounts 

Always show the inclusive counts.

Not part of default flags!

Constructor & Destructor Documentation

◆ AbstractAlbumTreeView()

Digikam::AbstractAlbumTreeView::AbstractAlbumTreeView ( QWidget *const  parent,
Flags  flags 
)

If you give 0 for model, call setAlbumModel afterwards. If you supply 0 for filterModel, call setAlbumFilterModel afterwards.

Member Function Documentation

◆ addCustomContextMenuActions()

void Digikam::AbstractAlbumTreeView::addCustomContextMenuActions ( ContextMenuHelper cmh,
Album album 
)
protectedvirtual
Parameters
cmhhelper object to create the context menu
albumtag on which the context menu will be created. May be null if it is requested on no tag entry

Reimplemented in Digikam::TagFilterView, Digikam::AlbumSelectTreeView, Digikam::TagCheckView, Digikam::TagFolderView, Digikam::EditableSearchTreeView, and Digikam::NormalSearchTreeView.

◆ contextMenuIcon()

QPixmap Digikam::AbstractAlbumTreeView::contextMenuIcon ( ) const
protectedvirtual
Returns
the icon for the context menu

◆ contextMenuTitle()

QString Digikam::AbstractAlbumTreeView::contextMenuTitle ( ) const
protectedvirtual
Returns
title for the context menu

Reimplemented in Digikam::TagFolderView, and Digikam::EditableSearchTreeView.

◆ doLoadState()

void Digikam::AbstractAlbumTreeView::doLoadState ( )
overridevirtual

Therefore the config is first parsed into d->statesByAlbumId which holds the state of all tree view entries indexed by album id. Afterwards an initial sync run is done restoring the state of all model entries that are already present at this time. Every processed entry is removed from d->statesByAlbumId. If there are still entries left in this map we assume that the model is not fully loaded at the moment. Therefore the rowsInserted signal is connected to a slot that restores the state of new rows based on the remaining entries in d->statesByAlbumId.

Implements Digikam::StateSavingObject.

Reimplemented in Digikam::AbstractCheckableAlbumTreeView, and Digikam::TagCheckView.

◆ doSaveState()

void Digikam::AbstractAlbumTreeView::doSaveState ( )
overridevirtual

◆ expandEverything

void Digikam::AbstractAlbumTreeView::expandEverything ( const QModelIndex &  index)
slot
Parameters
indexthe index to start expanding everything

◆ expandMatches()

bool Digikam::AbstractAlbumTreeView::expandMatches ( const QModelIndex &  index)
Parameters
indexthe index to start ensuring expansion state
Returns
true if there was a match under index. This return value can normally be ignored by the caller because it is only used for an internal recursion.

◆ handleCustomContextMenuAction()

void Digikam::AbstractAlbumTreeView::handleCustomContextMenuAction ( QAction *  action,
const AlbumPointer< Album > &  album 
)
protectedvirtual
Parameters
actionthe action that was chosen by the user, may be null if none of the custom actions were selected
albumthe tag on which the context menu was requested. May be null if there was no

Reimplemented in Digikam::TagFilterView, Digikam::AlbumSelectTreeView, Digikam::TagFolderView, Digikam::EditableSearchTreeView, and Digikam::NormalSearchTreeView.

◆ indexVisuallyAt()

QModelIndex Digikam::AbstractAlbumTreeView::indexVisuallyAt ( const QPoint &  p)
Parameters
pmust be in the viewport currently. Decoration will not be included. Suitable for mouse click positions.

◆ pixmapForDrag()

QPixmap Digikam::AbstractAlbumTreeView::pixmapForDrag ( const QStyleOptionViewItem &  option,
QList< QModelIndex >  indexes 
)
protectedvirtual

◆ selectedAlbumsChanged

void Digikam::AbstractAlbumTreeView::selectedAlbumsChanged ( const QList< Album * > &  selectedAlbums)
signal

Use currentChanged unless in multi-selection mode.

◆ selectedItems()

QList< Album * > Digikam::AbstractAlbumTreeView::selectedItems ( )
Returns
selected Items

◆ setAlbumFilterModel()

void Digikam::AbstractAlbumTreeView::setAlbumFilterModel ( AlbumFilterModel *const  filterModel)
protectedvirtual
Note
When only single selection was available, everything was implemented using currentAlbum() which was equal with selectedAlbum() after enabling multiple selection they are no longer the same and some options must use selected others only currentAlbum Now AlbumManager implementation is a little bit of mess because selected are now currentAlbums().

◆ setAlbumManagerCurrentAlbum()

void Digikam::AbstractAlbumTreeView::setAlbumManagerCurrentAlbum ( const bool  setCurrentAlbum)

Other treeview are self-contained and shall not change the current album. Default: false

◆ setContextMenuIcon()

void Digikam::AbstractAlbumTreeView::setContextMenuIcon ( const QPixmap &  pixmap)

This is used by the default implementation of contextMenuIcon() and contextMenuTitle(). You can alternatively reimplement these methods.

◆ setCurrentAlbums

void Digikam::AbstractAlbumTreeView::setCurrentAlbums ( const QList< Album * > &  albums,
bool  selectInAlbumManager = true 
)
virtualslot
Parameters
albumsthe albums to select
selectInAlbumManagerthe album will be set as current album, if both this parameter is true and setAlbumManagerCurrentAlbum() was set to true.

◆ setEnableContextMenu()

void Digikam::AbstractAlbumTreeView::setEnableContextMenu ( const bool  enable)

More detailed decision at which position a menu can be shown and where not can be made by implementing showContextMenuAt.

Parameters
enableif true, a context menu can be shown

◆ setSelectAlbumOnClick()

void Digikam::AbstractAlbumTreeView::setSelectAlbumOnClick ( const bool  selectOnClick)
Parameters
selectOnClickif true, a click on an item automatically sets this item as the current album in the album manager

◆ setSelectOnContextMenu()

void Digikam::AbstractAlbumTreeView::setSelectOnContextMenu ( const bool  select)

Defaults to true.

Parameters
selecttrue if a context menu request shall select the album

◆ showContextMenuAt()

bool Digikam::AbstractAlbumTreeView::showContextMenuAt ( QContextMenuEvent *  event,
Album albumForEvent 
)
protectedvirtual
Parameters
eventcontext menu event to react on
albumForEventthe album at the mouse position or null if there is no album at that position
Returns
true if a context menu shall be displayed at the event coordinates, else false

◆ slotRootAlbumAvailable

void Digikam::AbstractAlbumTreeView::slotRootAlbumAvailable ( )
protectedvirtualslot
Note
override if implemented behavior is not as intended