#include <entitytreemodel.h>

Inheritance diagram for Akonadi::EntityTreeModel:

Public Types
enum	CollectionFetchStrategy { FetchNoCollections, FetchFirstLevelChildCollections, FetchCollectionsRecursive, InvisibleCollectionFetch }

enum	FetchState { IdleState, FetchingState }

enum	HeaderGroup { EntityTreeHeaders, CollectionTreeHeaders, ItemListHeaders, UserHeaders = 10, EndHeaderGroup = 32 }

enum	ItemPopulationStrategy { NoItemPopulation, ImmediatePopulation, LazyPopulation }

enum	Roles { ItemIdRole = Qt::UserRole + 1, ItemRole = Qt::UserRole + 2, MimeTypeRole = Qt::UserRole + 3, CollectionIdRole = Qt::UserRole + 10, CollectionRole = Qt::UserRole + 11, RemoteIdRole, CollectionChildOrderRole, AmazingCompletionRole, ParentCollectionRole, ColumnCountRole, LoadedPartsRole, AvailablePartsRole, SessionRole, CollectionRefRole, CollectionDerefRole, PendingCutRole, EntityUrlRole, UnreadCountRole, FetchStateRole, CollectionSyncProgressRole, IsPopulatedRole, OriginalCollectionNameRole, UserRole = Qt::UserRole + 500, TerminalUserRole = 2000, EndRole = 65535 }

Signals
void	collectionFetched (int collectionId)

void	collectionPopulated (Akonadi::Collection::Id collectionId)

void	collectionTreeFetched (const Akonadi::Collection::List &collections)

Public Member Functions
	EntityTreeModel (ChangeRecorder monitor, QObject parent=0)

virtual	~EntityTreeModel ()

virtual bool	canFetchMore (const QModelIndex &parent) const

CollectionFetchStrategy	collectionFetchStrategy () const

virtual int	columnCount (const QModelIndex &parent=QModelIndex()) const

virtual QVariant	data (const QModelIndex &index, int role=Qt::DisplayRole) const

virtual bool	dropMimeData (const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

virtual void	fetchMore (const QModelIndex &parent)

virtual Qt::ItemFlags	flags (const QModelIndex &index) const

virtual bool	hasChildren (const QModelIndex &parent=QModelIndex()) const

virtual QVariant	headerData (int section, Qt::Orientation orientation, int role=Qt::DisplayRole) const

bool	includeRootCollection () const

AKONADI_DEPRECATED bool	includeUnsubscribed () const

virtual QModelIndex	index (int row, int column, const QModelIndex &parent=QModelIndex()) const

bool	isCollectionPopulated (Akonadi::Collection::Id) const

bool	isCollectionTreeFetched () const

bool	isFullyPopulated () const

ItemPopulationStrategy	itemPopulationStrategy () const

Akonadi::CollectionFetchScope::ListFilter	listFilter () const

virtual QModelIndexList	match (const QModelIndex &start, int role, const QVariant &value, int hits=1, Qt::MatchFlags flags=Qt::MatchFlags(Qt::MatchStartsWith\|Qt::MatchWrap)) const

virtual QMimeData *	mimeData (const QModelIndexList &indexes) const

virtual QStringList	mimeTypes () const

virtual QModelIndex	parent (const QModelIndex &index) const

QString	rootCollectionDisplayName () const

virtual int	rowCount (const QModelIndex &parent=QModelIndex()) const

void	setCollectionFetchStrategy (CollectionFetchStrategy strategy)

void	setCollectionMonitored (const Akonadi::Collection &col, bool monitored=true)

void	setCollectionReferenced (const Akonadi::Collection &col, bool referenced=true)

void	setCollectionsMonitored (const Akonadi::Collection::List &collections)

virtual bool	setData (const QModelIndex &index, const QVariant &value, int role=Qt::EditRole)

void	setIncludeRootCollection (bool include)

AKONADI_DEPRECATED void	setIncludeUnsubscribed (bool show)

void	setItemPopulationStrategy (ItemPopulationStrategy strategy)

void	setListFilter (Akonadi::CollectionFetchScope::ListFilter filter)

void	setRootCollectionDisplayName (const QString &name)

void	setShowSystemEntities (bool show)

virtual Qt::DropActions	supportedDropActions () const

bool	systemEntitiesShown () const

Public Member Functions inherited from QAbstractItemModel
	QAbstractItemModel (QObject *parent)

virtual QModelIndex	buddy (const QModelIndex &index) const

virtual int	columnCount (const QModelIndex &parent) const =0

void	columnsAboutToBeInserted (const QModelIndex &parent, int start, int end)

void	columnsAboutToBeMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

void	columnsAboutToBeRemoved (const QModelIndex &parent, int start, int end)

void	columnsInserted (const QModelIndex &parent, int start, int end)

void	columnsMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

void	columnsRemoved (const QModelIndex &parent, int start, int end)

virtual QVariant	data (const QModelIndex &index, int role) const =0

void	dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight)

bool	hasIndex (int row, int column, const QModelIndex &parent) const

void	headerDataChanged (Qt::Orientation orientation, int first, int last)

virtual QModelIndex	index (int row, int column, const QModelIndex &parent) const =0

bool	insertColumn (int column, const QModelIndex &parent)

virtual bool	insertColumns (int column, int count, const QModelIndex &parent)

bool	insertRow (int row, const QModelIndex &parent)

virtual bool	insertRows (int row, int count, const QModelIndex &parent)

virtual QMap< int, QVariant >	itemData (const QModelIndex &index) const

void	layoutAboutToBeChanged ()

void	layoutChanged ()

virtual QModelIndexList	match (const QModelIndex &start, int role, const QVariant &value, int hits, QFlags< Qt::MatchFlag > flags) const

void	modelAboutToBeReset ()

void	modelReset ()

virtual QModelIndex	parent (const QModelIndex &index) const =0

bool	removeColumn (int column, const QModelIndex &parent)

virtual bool	removeColumns (int column, int count, const QModelIndex &parent)

bool	removeRow (int row, const QModelIndex &parent)

virtual bool	removeRows (int row, int count, const QModelIndex &parent)

virtual void	revert ()

const QHash< int, QByteArray > &	roleNames () const

virtual int	rowCount (const QModelIndex &parent) const =0

void	rowsAboutToBeInserted (const QModelIndex &parent, int start, int end)

void	rowsAboutToBeMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

void	rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end)

void	rowsInserted (const QModelIndex &parent, int start, int end)

void	rowsMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

void	rowsRemoved (const QModelIndex &parent, int start, int end)

virtual bool	setHeaderData (int section, Qt::Orientation orientation, const QVariant &value, int role)

virtual bool	setItemData (const QModelIndex &index, const QMap< int, QVariant > &roles)

void	setSupportedDragActions (QFlags< Qt::DropAction > actions)

QModelIndex	sibling (int row, int column, const QModelIndex &index) const

virtual void	sort (int column, Qt::SortOrder order)

virtual QSize	span (const QModelIndex &index) const

virtual bool	submit ()

Qt::DropActions	supportedDragActions () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

	QObject (QObject parent, const char name)

bool	blockSignals (bool block)

QObject *	child (const char objName, const char inheritsClass, bool recursiveSearch) const

const QObjectList &	children () const

const char *	className () const

bool	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const QObject receiver, const char method)

bool	disconnect (const char signal, const QObject receiver, const char *method)

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name) const

QList< T >	findChildren (const QRegExp &regExp) const

QList< T >	findChildren (const QString &name) const

bool	inherits (const char *className) const

void	insertChild (QObject *object)

void	installEventFilter (QObject *filterObj)

bool	isA (const char *className) const

bool	isWidgetType () const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

const char *	name () const

const char *	name (const char *defaultName) const

QString	objectName () const

QObject *	parent () const

QVariant	property (const char *name) const

void	removeChild (QObject *object)

void	removeEventFilter (QObject *obj)

void	setName (const char *name)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval)

QThread *	thread () const

Static Public Member Functions
static QModelIndexList	modelIndexesForItem (const QAbstractItemModel *model, const Item &item)

static QModelIndex	modelIndexForCollection (const QAbstractItemModel *model, const Collection &collection)

Static Public Member Functions inherited from QObject
bool	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Protected Member Functions
void	clearAndReset ()

virtual int	entityColumnCount (HeaderGroup headerGroup) const

virtual QVariant	entityData (const Item &item, int column, int role=Qt::DisplayRole) const

virtual QVariant	entityData (const Collection &collection, int column, int role=Qt::DisplayRole) const

virtual QVariant	entityHeaderData (int section, Qt::Orientation orientation, int role, HeaderGroup headerGroup) const

virtual bool	entityMatch (const Item &item, const QVariant &value, Qt::MatchFlags flags) const

virtual bool	entityMatch (const Collection &collection, const QVariant &value, Qt::MatchFlags flags) const

Protected Member Functions inherited from QAbstractItemModel
void	beginInsertColumns (const QModelIndex &parent, int first, int last)

void	beginInsertRows (const QModelIndex &parent, int first, int last)

bool	beginMoveColumns (const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

bool	beginMoveRows (const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

void	beginRemoveColumns (const QModelIndex &parent, int first, int last)

void	beginRemoveRows (const QModelIndex &parent, int first, int last)

void	beginResetModel ()

void	changePersistentIndex (const QModelIndex &from, const QModelIndex &to)

void	changePersistentIndexList (const QModelIndexList &from, const QModelIndexList &to)

QModelIndex	createIndex (int row, int column, void *ptr) const

QModelIndex	createIndex (int row, int column, int id) const

QModelIndex	createIndex (int row, int column, quint32 id) const

void	endInsertColumns ()

void	endInsertRows ()

void	endMoveColumns ()

void	endMoveRows ()

void	endRemoveColumns ()

void	endRemoveRows ()

void	endResetModel ()

QModelIndexList	persistentIndexList () const

void	reset ()

void	resetInternalData ()

void	setRoleNames (const QHash< int, QByteArray > &roleNames)

Protected Member Functions inherited from QObject
bool	checkConnectArgs (const char signal, const QObject object, const char *method)

virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const char *signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const char *signal)

int	receivers (const char *signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Additional Inherited Members
Static Protected Member Functions inherited from QObject
QByteArray	normalizeSignalSlot (const char *signalSlot)

Properties inherited from QObject
	objectName

Detailed Description

A model for collections and items together.

Akonadi models and views provide a high level way to interact with the akonadi server. Most applications will use these classes.

Models provide an interface for viewing, updating, deleting and moving Items and Collections. Additionally, the models are updated automatically if another application changes the data or inserts of deletes items etc.

Note: The EntityTreeModel should be used with the EntityTreeView or the EntityListView class either directly or indirectly via proxy models.

Retrieving Collections and Items from the model

If you want to retrieve and Item or Collection from the model, and already have a valid QModelIndex for the correct row, the Collection can be retrieved like this:

Collection col = index.data( EntityTreeModel::CollectionRole ).value<Collection>();

And similarly for Items. This works even if there is a proxy model between the calling code and the EntityTreeModel.

If you want to retrieve a Collection for a particular Collection::Id and you do not yet have a valid QModelIndex, use modelIndexForCollection.

Using EntityTreeModel in your application

The responsibilities which fall to the application developer are

Configuring the ChangeRecorder and EntityTreeModel
Making use of this class via proxy models
Subclassing for type specific display information

Creating and configuring the EntityTreeModel

This class is a wrapper around a Akonadi::ChangeRecorder object. The model represents a part of the collection and item tree configured in the ChangeRecorder. The structure of the model mirrors the structure of Collections and Items on the Akonadi server.

The following code creates a model which fetches items and collections relevant to addressees (contacts), and automatically manages keeping the items up to date.

ChangeRecorder *changeRecorder = new ChangeRecorder( this );
changeRecorder->setCollectionMonitored( Collection::root() );
changeRecorder->setMimeTypeMonitored( KABC::addresseeMimeType() );
changeRecorder->setSession( session );
EntityTreeModel *model = new EntityTreeModel( changeRecorder, this );
EntityTreeView *view = new EntityTreeView( this );
view->setModel( model );

The EntityTreeModel will show items of a different type by changing the line

changeRecorder->setMimeTypeMonitored( KABC::addresseeMimeType() );

to a different mimetype. KABC::addresseeMimeType() is an alias for "text/directory". If changed to KMime::Message::mimeType() (an alias for "message/rfc822") the model would instead contain emails. The model can be configured to contain items of any mimetype known to Akonadi.

Note: The EntityTreeModel does some extra configuration on the Monitor, such as setting itemFetchScope() and collectionFetchScope() to retrieve all ancestors. This is necessary for proper function of the model.

See also: Akonadi::ItemFetchScope::AncestorRetrieval.; akonadi-mimetypes.

The EntityTreeModel can be further configured for certain behaviours such as fetching of collections and items.

The model can be configured to not fetch items into the model (ie, fetch collections only) by setting

entityTreeModel->setItemPopulationStrategy( EntityTreeModel::NoItemPopulation );

The items may be fetched lazily, i.e. not inserted into the model until request by the user for performance reasons.

The Collection tree is always built immediately if Collections are to be fetched.

entityTreeModel->setItemPopulationStrategy( EntityTreeModel::LazyPopulation );

This will typically be used with a EntityMimeTypeFilterModel in a configuration such as KMail4.5 or AkonadiConsole.

The CollectionFetchStrategy determines how the model will be populated with Collections. That is, if FetchNoCollections is set, no collections beyond the root of the model will be fetched. This can be used in combination with setting a particular Collection to monitor.

// Get an collection id from a config file.
Collection::Id id;
monitor->setCollectionMonitored( Collection( id ) );
// ... Other initialization code.
entityTree->setCollectionFetchStrategy( FetchNoCollections );

This has the effect of creating a model of only a list of Items, and not collections. This is similar in behaviour and aims to the ItemModel. By using FetchFirstLevelCollections instead, a mixed list of entities can be created.

Note: It is important that you set only one Collection to be monitored in the monitor object. This one collection will be the root of the tree. If you need a model with a more complex structure, consider monitoring a common ancestor and using a SelectionProxyModel.

See also: lazy-model-population

It is also possible to show the root Collection as part of the selectable model:

entityTree->setIncludeRootCollection( true );

By default the displayed name of the root collection is '[*]', because it doesn't require i18n, and is generic. It can be changed too.

entityTree->setIncludeRootCollection( true );

entityTree->setRootCollectionDisplayName( i18nc( "Name of top level for all addressbooks in the application", "[All AddressBooks]" ) )

This feature is used in KAddressBook.

If items are to be fetched by the model, it is necessary to specify which parts of the items are to be fetched, using the ItemFetchScope class. By default, only the basic metadata is fetched. To fetch all item data, including all attributes:

changeRecorder->itemFetchScope().fetchFullPayload();

changeRecorder->itemFetchScope().fetchAllAttributes();

Using EntityTreeModel with Proxy models

An Akonadi::SelectionProxyModel can be used to simplify managing selection in one view through multiple proxy models to a representation in another view. The selectionModel of the initial view is used to create a proxied model which filters out anything not related to the current selection.

// ... create an EntityTreeModel
collectionTree = new EntityMimeTypeFilterModel( this );
collectionTree->setSourceModel( entityTreeModel );
// Include only collections in this proxy model.
collectionTree->addMimeTypeInclusionFilter( Collection::mimeType() );
collectionTree->setHeaderGroup( EntityTreeModel::CollectionTreeHeaders );
treeview->setModel(collectionTree);
// SelectionProxyModel can handle complex selections:
treeview->setSelectionMode( QAbstractItemView::ExtendedSelection );
SelectionProxyModel *selProxy = new SelectionProxyModel( treeview->selectionModel(), this );
selProxy->setSourceModel( entityTreeModel );
itemList = new EntityMimeTypeFilterModel( this );
itemList->setSourceModel( selProxy );
// Filter out collections. Show only items.
itemList->addMimeTypeExclusionFilter( Collection::mimeType() );
itemList->setHeaderGroup( EntityTreeModel::ItemListHeaders );
EntityTreeView *itemView = new EntityTreeView( splitter );
itemView->setModel( itemList );

The SelectionProxyModel can handle complex selections.

See the KSelectionProxyModel documentation for the valid configurations of a Akonadi::SelectionProxyModel.

Obviously, the SelectionProxyModel may be used in a view, or further processed with other proxy models. Typically, the result from this model will be further filtered to remove collections from the item list as in the above example.

There are several advantages of using EntityTreeModel with the SelectionProxyModel, namely the items can be fetched and cached instead of being fetched many times, and the chain of proxies from the core model to the view is automatically handled. There is no need to manage all the mapToSource and mapFromSource calls manually.

A KDescendantsProxyModel can be used to represent all descendants of a model as a flat list. For example, to show all descendant items in a selected Collection in a list:

collectionTree = new EntityMimeTypeFilterModel( this );
collectionTree->setSourceModel( entityTreeModel );
// Include only collections in this proxy model.
collectionTree->addMimeTypeInclusionFilter( Collection::mimeType() );
collectionTree->setHeaderGroup( EntityTreeModel::CollectionTreeHeaders );
treeview->setModel( collectionTree );
SelectionProxyModel *selProxy = new SelectionProxyModel( treeview->selectionModel(), this );
selProxy->setSourceModel( entityTreeModel );
descendedList = new DescendantEntitiesProxyModel( this );
descendedList->setSourceModel( selProxy );
itemList = new EntityMimeTypeFilterModel( this );
itemList->setSourceModel( descendedList );
// Exclude collections from the list view.
itemList->addMimeTypeExclusionFilter( Collection::mimeType() );
itemList->setHeaderGroup( EntityTreeModel::ItemListHeaders );
listView = new EntityTreeView( this );
listView->setModel( itemList );

Note that it is important in this case to use the DescendantEntitesProxyModel before the EntityMimeTypeFilterModel. Otherwise, by filtering out the collections first, you would also be filtering out their child items.

This pattern is used in KAddressBook.

It would not make sense to use a KDescendantsProxyModel with LazyPopulation.

Subclassing EntityTreeModel

Usually an application will create a subclass of an EntityTreeModel and use that in several views via proxy models.

The subclassing is necessary in order for the data in the model to have type-specific representation in applications

For example, the headerData for an EntityTreeModel will be different depending on whether it is in a view showing only Collections in which case the header data should be "AddressBooks" for example, or only Items, in which case the headerData would be for example "Family Name", "Given Name" and "Email addres" for contacts or "Subject", "Sender", "Date" in the case of emails.

Additionally, the actual data shown in the rows of the model should be type specific.

In summary, it must be possible to have different numbers of columns, different data in hte rows of those columns, and different titles for each column depending on the contents of the view.

The way this is accomplished is by using the EntityMimeTypeFilterModel for splitting the model into a "CollectionTree" and an "Item List" as in the above example, and using a type-specific EntityTreeModel subclass to return the type-specific data, typically for only one type (for example, contacts or emails).

The following protected virtual methods should be implemented in the subclass:

int entityColumnCount( HeaderGroup headerGroup ) const; – Implement to return the number of columns for a HeaderGroup. If the HeaderGroup is CollectionTreeHeaders, return the number of columns to display for the Collection tree, and if it is ItemListHeaders, return the number of columns to display for the item. In the case of addressee, this could be for example, two (for given name and family name) or for emails it could be three (for subject, sender, date). This is a decision of the subclass implementor.
QVariant entityHeaderData( int section, Qt::Orientation orientation, int role, HeaderGroup headerGroup ) const; – Implement to return the data for each section for a HeaderGroup. For example, if the header group is CollectionTreeHeaders in a contacts model, the string "Address books" might be returned for column 0, whereas if the headerGroup is ItemListHeaders, the strings "Given Name", "Family Name", "Email Address" might be returned for the columns 0, 1, and 2.
QVariant entityData( const Collection &collection, int column, int role = Qt::DisplayRole ) const; – Implement to return data for a particular Collection. Typically this will be the name of the collection or the EntityDisplayAttribute.
QVariant entityData( const Item &item, int column, int role = Qt::DisplayRole ) const; – Implement to return the data for a particular item and column. In the case of email for example, this would be the actual subject, sender and date of the email.

Note: The entityData methods are just for convenience. the QAbstractItemMOdel::data method can be overridden if required.

The application writer must then properly configure proxy models for the views, so that the correct data is shown in the correct view. That is the purpose of these lines in the above example

collectionTree->setHeaderGroup( EntityTreeModel::CollectionTreeHeaders );

itemList->setHeaderGroup( EntityTreeModel::ItemListHeaders );

Progress reporting

The EntityTreeModel uses asynchronous Akonadi::Job instances to fill and update itself. For example, a job is run to fetch the contents of collections (that is, list the items in it). Additionally, individual Akonadi::Items can be fetched in different parts at different times.

To indicate that such a job is underway, the EntityTreeModel makes the FetchState available. The FetchState returned from a QModelIndex representing a Akonadi::Collection will be FetchingState if a listing of the items in that collection is underway, otherwise the state is IdleState.

Author: Stephen Kelly steve.nosp@m.ire@.nosp@m.gmail.nosp@m..com

Since: 4.4

Definition at line 318 of file entitytreemodel.h.

Member Enumeration Documentation

enum Akonadi::EntityTreeModel::CollectionFetchStrategy

Describes what collections shall be fetched by and represent in the model.

Enumerator
FetchNoCollections	Fetches nothing. This creates an empty model.
FetchFirstLevelChildCollections	Fetches first level collections in the root collection.
FetchCollectionsRecursive	Fetches collections in the root collection recursively. This is the default.
InvisibleCollectionFetch	Fetches collections, but does not put them in the model. This can be used to create a list of items in all collections. The ParentCollectionRole can still be used to retrieve the parent collection of an Item. Since 4.5

Definition at line 527 of file entitytreemodel.h.

enum Akonadi::EntityTreeModel::FetchState

Describes the state of fetch jobs related to particular collections.

QModelIndex collectionIndex = getIndex();
if (collectionIndex.data(EntityTreeModel::FetchStateRole).toLongLong() == FetchingState) {
  // There is a fetch underway
} else {
  // There is no fetch underway.
}

Since: 4.5

Enumerator
IdleState	There is no fetch of items in this collection in progress.
FetchingState	There is a fetch of items in this collection in progress.

Definition at line 374 of file entitytreemodel.h.

enum Akonadi::EntityTreeModel::HeaderGroup

Describes what header information the model shall return.

Enumerator
EntityTreeHeaders	Header information for a tree with collections and items.
CollectionTreeHeaders	Header information for a collection-only tree.
ItemListHeaders	Header information for a list of items.
UserHeaders	Last header information for submodel extensions.
EndHeaderGroup	Last headergroup role. Don't use a role beyond this or headerData will break.

Definition at line 383 of file entitytreemodel.h.

enum Akonadi::EntityTreeModel::ItemPopulationStrategy

Describes how the model should populated its items.

Enumerator
NoItemPopulation	Do not include items in the model.
ImmediatePopulation	Retrieve items immediately when their parent is in the model. This is the default.
LazyPopulation	Fetch items only when requested (using canFetchMore/fetchMore)

Definition at line 408 of file entitytreemodel.h.

enum Akonadi::EntityTreeModel::Roles

Describes the roles for items.

Roles for collections are defined by the superclass.

Enumerator
ItemIdRole	The item id.
ItemRole	The Item.
MimeTypeRole	The mimetype of the entity.
CollectionIdRole	The collection id.
CollectionRole	The collection.
RemoteIdRole	The remoteId of the entity.
CollectionChildOrderRole	Ordered list of child items if available.
AmazingCompletionRole	Role used to implement amazing completion.
ParentCollectionRole	The parent collection of the entity.
ColumnCountRole	Used by proxies to determine the number of columns for a header group.
LoadedPartsRole	Parts available in the model for the item.
AvailablePartsRole	Parts available in the Akonadi server for the item.
SessionRole	The Session used by this model
CollectionRefRole	Used to increase the reference count on a Collection
CollectionDerefRole	Used to decrease the reference count on a Collection
PendingCutRole	Used to indicate items which are to be cut
EntityUrlRole	The akonadi:/ Url of the entity as a string. Item urls will contain the mimetype.
UnreadCountRole	Returns the number of unread items in a collection. Since 4.5
FetchStateRole	Returns the FetchState of a particular item. Since 4.5
CollectionSyncProgressRole	Returns the progress of synchronization in percent for a particular collection. Since 4.6. Deprecated since 4.14.3.
IsPopulatedRole	Returns whether a Collection has been populated, i.e. whether its items have been fetched. Since 4.10
OriginalCollectionNameRole	Returns original name for collection. Since 4.14
UserRole	First role for user extensions.
TerminalUserRole	Last role for user extensions. Don't use a role beyond this or headerData will break.

Definition at line 326 of file entitytreemodel.h.

Constructor & Destructor Documentation

EntityTreeModel::EntityTreeModel	(	ChangeRecorder *	monitor,
		QObject *	parent = `0`
	)

explicit

Creates a new entity tree model.

Parameters

monitor	The ChangeRecorder whose entities should be represented in the model.
parent	The parent object.

Definition at line 53 of file entitytreemodel.cpp.

EntityTreeModel::~EntityTreeModel ( )

virtual

Destroys the entity tree model.

Definition at line 68 of file entitytreemodel.cpp.

Member Function Documentation

void EntityTreeModel::clearAndReset ( )

protected

Clears and resets the model.

Always call this instead of the reset method in the superclass. Using the reset method will not reliably clear or refill the model.

Definition at line 155 of file entitytreemodel.cpp.

void Akonadi::EntityTreeModel::collectionFetched ( int collectionId )

signal

Emitted once a collection has been fetched for the very first time.

This is like a dataChanged(), but specific to the initial loading, in order to update the GUI (window caption, state of actions). Usually, the GUI uses Akonadi::Monitor to be notified of further changes to the collections.

Parameters

collectionId the identifier of the fetched collection

Since: 4.9.3

EntityTreeModel::CollectionFetchStrategy EntityTreeModel::collectionFetchStrategy ( ) const

Returns the collection fetch strategy of the model.

Definition at line 1207 of file entitytreemodel.cpp.

void Akonadi::EntityTreeModel::collectionPopulated ( Akonadi::Collection::Id collectionId )

signal

Signal emitted when a collection has been populated, i.e.

its items have been fetched.

Parameters

collectionId id of the collection which has been populated

See also: collectionTreeFetched

Since: 4.10

void Akonadi::EntityTreeModel::collectionTreeFetched ( const Akonadi::Collection::List & collections )

signal

Signal emitted when the collection tree has been fetched for the first time.

Parameters

collections list of collections which have been fetched

See also: isCollectionTreeFetched, collectionPopulated

Since: 4.10

QVariant EntityTreeModel::entityData	(	const Item &	item,
		int	column,
		int	role = `Qt::DisplayRole`
	)		const

protectedvirtual

Provided for convenience of subclasses.

Definition at line 173 of file entitytreemodel.cpp.

QVariant EntityTreeModel::entityData	(	const Collection &	collection,
		int	column,
		int	role = `Qt::DisplayRole`
	)		const

protectedvirtual

Provided for convenience of subclasses.

Definition at line 203 of file entitytreemodel.cpp.

QVariant EntityTreeModel::entityHeaderData	(	int	section,
		Qt::Orientation	orientation,
		int	role,
		HeaderGroup	headerGroup
	)		const

protectedvirtual

Reimplement this to provide different header data.

This is needed when using one model with multiple proxies and views, and each should show different header data.

Definition at line 730 of file entitytreemodel.cpp.

bool EntityTreeModel::entityMatch	(	const Item &	item,
		const QVariant &	value,
		Qt::MatchFlags	flags
	)		const

protectedvirtual

Reimplement this in a subclass to return true if item matches value with flags in the AmazingCompletionRole.

Definition at line 977 of file entitytreemodel.cpp.

bool EntityTreeModel::entityMatch	(	const Collection &	collection,
		const QVariant &	value,
		Qt::MatchFlags	flags
	)		const

protectedvirtual

Reimplement this in a subclass to return true if collection matches value with flags in the AmazingCompletionRole.

Definition at line 985 of file entitytreemodel.cpp.

bool EntityTreeModel::includeRootCollection ( ) const

Returns whether the root collection is provided by the model.

Definition at line 1162 of file entitytreemodel.cpp.

bool EntityTreeModel::includeUnsubscribed ( ) const

Returns whether unsubscribed entities will be included in the listing.

Since: 4.5

Deprecated:: use listFilter instead

Definition at line 85 of file entitytreemodel.cpp.

bool EntityTreeModel::isCollectionPopulated ( Akonadi::Collection::Id id ) const

Returns whether the collection has been populated.

See also: collectionPopulated

Since: 4.12

Definition at line 965 of file entitytreemodel.cpp.

bool EntityTreeModel::isCollectionTreeFetched ( ) const

Returns whether the collection tree has been fetched at initialisation.

See also: collectionTreeFetched

Since: 4.10

Definition at line 958 of file entitytreemodel.cpp.

bool EntityTreeModel::isFullyPopulated ( ) const

Returns whether the model is fully populated.

Returns true once the collection tree has been fetched and all collections have been populated.

See also: isCollectionPopulated; isCollectionTreeFetched

Since: 4.14

Definition at line 971 of file entitytreemodel.cpp.

EntityTreeModel::ItemPopulationStrategy EntityTreeModel::itemPopulationStrategy ( ) const

Returns the item population strategy of the model.

Definition at line 1148 of file entitytreemodel.cpp.

CollectionFetchScope::ListFilter EntityTreeModel::listFilter ( ) const

Returns the currently used listfilter.

Since: 4.14

Definition at line 99 of file entitytreemodel.cpp.

QModelIndexList EntityTreeModel::match	(	const QModelIndex &	start,
		int	role,
		const QVariant &	value,
		int	hits = `1`,
		Qt::MatchFlags	flags = `Qt::MatchFlags(Qt::MatchStartsWith \| Qt::MatchWrap)`
	)		const

virtual

Reimplemented to handle the AmazingCompletionRole.

Definition at line 993 of file entitytreemodel.cpp.

QModelIndexList EntityTreeModel::modelIndexesForItem	(	const QAbstractItemModel *	model,
		const Item &	item
	)

static

Returns a QModelIndex in model which points to item.

This method can be used through proxy models if model is a proxy model.

Parameters

model	the model to query for the item
item	the item to look for

See also: modelIndexForCollection

Since: 4.5

Definition at line 1247 of file entitytreemodel.cpp.

QModelIndex EntityTreeModel::modelIndexForCollection	(	const QAbstractItemModel *	model,
		const Collection &	collection
	)

static

Returns a QModelIndex in model which points to collection.

This method can be used through proxy models if model is a proxy model.

EntityTreeModel *model = getEntityTreeModel();
QSortFilterProxyModel *proxy1 = new QSortFilterProxyModel;
proxy1->setSourceModel(model);
QSortFilterProxyModel *proxy2 = new QSortFilterProxyModel;
proxy2->setSourceModel(proxy1);
...
QModelIndex idx = EntityTreeModel::modelIndexForCollection(proxy2, Collection(colId));
if (!idx.isValid())
  // Collection with id colId is not in the proxy2.
  // Maybe it is filtered out if proxy 2 is only showing items? Make sure you use the correct proxy.
  return;
Collection collection = idx.data( EntityTreeModel::CollectionRole ).value<Collection>();
// collection has the id colId, and all other attributes already fetched by the model such as name, remoteId, Akonadi::Attributes etc.

This can be useful for example if an id is stored in a config file and needs to be used in the application.

Note however, that to restore view state such as scrolling, selection and expansion of items in trees, the ETMViewStateSaver can be used for convenience.

See also: modelIndexesForItem

Since: 4.5

Definition at line 1238 of file entitytreemodel.cpp.

QString EntityTreeModel::rootCollectionDisplayName ( ) const

Returns the display name of the root collection.

Definition at line 1176 of file entitytreemodel.cpp.

void EntityTreeModel::setCollectionFetchStrategy ( CollectionFetchStrategy strategy )

Sets the collection fetch strategy of the model.

Definition at line 1182 of file entitytreemodel.cpp.

void EntityTreeModel::setCollectionMonitored	(	const Akonadi::Collection &	col,
		bool	monitored = `true`
	)

Adds or removes a specific collection from the monitored set without resetting the model.

Only call this if you're monitoring specific collections (not mimetype/resources/items).

Since: 4.14

See also: setCollectionsMonitored()

Definition at line 127 of file entitytreemodel.cpp.

void EntityTreeModel::setCollectionReferenced	(	const Akonadi::Collection &	col,
		bool	referenced = `true`
	)

References a collection and starts to monitor it.

Use this to temporarily include a collection that is not enabled.

Since: 4.14

Definition at line 133 of file entitytreemodel.cpp.

void EntityTreeModel::setCollectionsMonitored ( const Akonadi::Collection::List & collections )

Monitors the specified collections and resets the model.

Since: 4.14

Definition at line 114 of file entitytreemodel.cpp.

void EntityTreeModel::setIncludeRootCollection ( bool include )

Sets whether the root collection shall be provided by the model.

Parameters

include enables root collection if set as true

See also: setRootCollectionDisplayName()

Definition at line 1154 of file entitytreemodel.cpp.

void EntityTreeModel::setIncludeUnsubscribed ( bool show )

Sets whether unsubscribed entities will be included in the listing.

By default it's true

Parameters

show	enables displaying of unsubscribed entities if set as `true` Note that it is possible to change the monitor's fetchscope directly, bypassing this method, which will lead to inconsistencies. Use this method for turning on/off listing of subscribed folders.

Since: 4.5

Deprecated:: use setListFilter instead

Definition at line 90 of file entitytreemodel.cpp.

void EntityTreeModel::setItemPopulationStrategy ( ItemPopulationStrategy strategy )

Sets the item population strategy of the model.

Definition at line 1121 of file entitytreemodel.cpp.

void EntityTreeModel::setListFilter ( Akonadi::CollectionFetchScope::ListFilter filter )

Sets the currently used listfilter.

Since: 4.14

Definition at line 105 of file entitytreemodel.cpp.

void EntityTreeModel::setRootCollectionDisplayName ( const QString & name )

Sets the display name of the root collection of the model.

The default display name is "[*]".

Parameters

name	the name to display for the root collection

Note: The display name for the root collection is only used if the root collection has been included with setIncludeRootCollection().

Definition at line 1168 of file entitytreemodel.cpp.

void EntityTreeModel::setShowSystemEntities ( bool show )

Some Entities are hidden in the model, but exist for internal purposes, for example, custom object directories in groupware resources.

They are hidden by default, but can be shown by setting show to true.

Parameters

show	enabled displaying of hidden entities if set as `true` Most applications will not need to use this feature.

Definition at line 149 of file entitytreemodel.cpp.

bool EntityTreeModel::systemEntitiesShown ( ) const

Returns true if internal system entities are shown, and false otherwise.

Definition at line 143 of file entitytreemodel.cpp.

The documentation for this class was generated from the following files:

akonadi

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Retrieving Collections and Items from the model

Using EntityTreeModel in your application

Creating and configuring the EntityTreeModel

Using EntityTreeModel with Proxy models

Subclassing EntityTreeModel

Progress reporting

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

akonadi

kdepimlibs API Reference

Search