entitytreemodel.h

/*
    Copyright (c) 2008 Stephen Kelly <steveire@gmail.com>

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
    License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to the
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA.
*/

#ifndef AKONADI_ENTITYTREEMODEL_H
#define AKONADI_ENTITYTREEMODEL_H

#include "akonadi_export.h"

#include <akonadi/collection.h>
#include <akonadi/item.h>

#include <QtCore/QAbstractItemModel>
#include <QtCore/QStringList>

namespace Akonadi
{

class ChangeRecorder;
class CollectionStatistics;
class Item;
class ItemFetchScope;
class Monitor;
class Session;

class EntityTreeModelPrivate;

class AKONADI_EXPORT EntityTreeModel : public QAbstractItemModel
{
  Q_OBJECT

  public:
    enum Roles {
      //sebsauer, 2009-05-07; to be able here to keep the akonadi_next EntityTreeModel compatible with
      //the akonadi_old ItemModel and CollectionModel, we need to use the same int-values for
      //ItemRole, ItemIdRole and MimeTypeRole like the Akonadi::ItemModel is using and the same
      //CollectionIdRole and CollectionRole like the Akonadi::CollectionModel is using.
      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,                        
      UserRole = Qt::UserRole + 500,          
      TerminalUserRole = 2000,                
      EndRole = 65535
    };

    enum FetchState {
      IdleState,                              
      FetchingState                           
      // TODO: Change states for reporting of fetching payload parts of items.
    };

    enum HeaderGroup {
      EntityTreeHeaders,      
      CollectionTreeHeaders,  
      ItemListHeaders,        
      UserHeaders = 10,       
      EndHeaderGroup = 32     
      // Note that we're splitting up available roles for the header data hack and int(EndRole / TerminalUserRole) == 32
    };

    explicit EntityTreeModel( ChangeRecorder *monitor, QObject *parent = 0 );

    virtual ~EntityTreeModel();

    enum ItemPopulationStrategy {
      NoItemPopulation,    
      ImmediatePopulation, 
      LazyPopulation       
    };

    void setShowSystemEntities( bool show );

    bool systemEntitiesShown() const;

    bool includeUnsubscribed() const;

    void setIncludeUnsubscribed( bool show );

    void setItemPopulationStrategy( ItemPopulationStrategy strategy );

    ItemPopulationStrategy itemPopulationStrategy() const;

    void setIncludeRootCollection( bool include );

    bool includeRootCollection() const;

    void setRootCollectionDisplayName( const QString &name );

    QString rootCollectionDisplayName() const;

    enum CollectionFetchStrategy {
      FetchNoCollections,               
      FetchFirstLevelChildCollections,  
      FetchCollectionsRecursive,        
      InvisibleCollectionFetch          
    };

    void setCollectionFetchStrategy( CollectionFetchStrategy strategy );

    CollectionFetchStrategy collectionFetchStrategy() const;

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

    virtual QVariant data( const QModelIndex & index, int role = Qt::DisplayRole ) const;
    virtual QVariant headerData( int section, Qt::Orientation orientation, int role = Qt::DisplayRole ) const;

    virtual Qt::ItemFlags flags( const QModelIndex &index ) const;
    virtual QStringList mimeTypes() const;

    virtual Qt::DropActions supportedDropActions() const;
    virtual QMimeData *mimeData( const QModelIndexList &indexes ) const;
    virtual bool dropMimeData( const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent );
    virtual bool setData( const QModelIndex &index, const QVariant &value, int role = Qt::EditRole );

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

    // TODO: Review the implementations of these. I think they could be better.
    virtual bool canFetchMore( const QModelIndex & parent ) const;
    virtual void fetchMore( const QModelIndex & parent );
    virtual bool hasChildren( const QModelIndex &parent = QModelIndex() ) const;

    bool isCollectionTreeFetched() const;

    bool isCollectionPopulated( Akonadi::Collection::Id ) 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;

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

    static QModelIndexList modelIndexesForItem( const QAbstractItemModel *model, const Item &item );

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

    void collectionPopulated( Akonadi::Collection::Id collectionId );
    void collectionFetched(int collectionId);

  protected:
    void clearAndReset();

    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 int entityColumnCount( 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:
    //@cond PRIVATE
    Q_DECLARE_PRIVATE( EntityTreeModel )
    EntityTreeModelPrivate * d_ptr;
    EntityTreeModel( ChangeRecorder *monitor, EntityTreeModelPrivate *d, QObject* parent = 0 );
    //@endcond

private:
  //@cond PRIVATE
    // Make these private, they shouldn't be called by applications
    virtual bool insertRows( int , int, const QModelIndex& = QModelIndex() );
    virtual bool insertColumns( int, int, const QModelIndex& = QModelIndex() );
    virtual bool removeColumns( int, int, const QModelIndex& = QModelIndex() );
    virtual bool removeRows( int, int, const QModelIndex & = QModelIndex() );

    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionStatisticsChanged( Akonadi::Collection::Id,
                                                                         const Akonadi::CollectionStatistics& ) )

    Q_PRIVATE_SLOT( d_func(), void startFirstListJob() )
    Q_PRIVATE_SLOT( d_func(), void serverStarted() )

    Q_PRIVATE_SLOT( d_func(), void fetchJobDone( KJob *job ) )
    Q_PRIVATE_SLOT( d_func(), void rootFetchJobDone( KJob *job ) )
    Q_PRIVATE_SLOT( d_func(), void pasteJobDone( KJob *job ) )
    Q_PRIVATE_SLOT( d_func(), void updateJobDone( KJob *job ) )
    Q_PRIVATE_SLOT( d_func(), void firstFetchJobDone( KJob *job ) )

    Q_PRIVATE_SLOT( d_func(), void itemsFetched( Akonadi::Item::List ) )
    Q_PRIVATE_SLOT( d_func(), void itemsFetched( KJob* ) )
    Q_PRIVATE_SLOT( d_func(), void collectionsFetched( Akonadi::Collection::List ) )
    Q_PRIVATE_SLOT( d_func(), void allCollectionsFetched( Akonadi::Collection::List ) )
    Q_PRIVATE_SLOT( d_func(), void firstCollectionsFetched( Akonadi::Collection::List ) )
    Q_PRIVATE_SLOT( d_func(), void collectionListFetched( Akonadi::Collection::List ) )
    Q_PRIVATE_SLOT( d_func(), void topLevelCollectionsFetched( Akonadi::Collection::List ) )
    Q_PRIVATE_SLOT( d_func(), void ancestorsFetched( Akonadi::Collection::List ) )

    Q_PRIVATE_SLOT( d_func(), void monitoredMimeTypeChanged( const QString&, bool ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionsChanged( const Akonadi::Collection&, bool ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemsChanged( const Akonadi::Item&, bool ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredResourcesChanged( const QByteArray&, bool ) )

    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionAdded( const Akonadi::Collection&, const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionRemoved( const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionChanged( const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionMoved( const Akonadi::Collection&, const Akonadi::Collection&,
                                                             const Akonadi::Collection&) )
    Q_PRIVATE_SLOT( d_func(), void collectionSubscribed( const Akonadi::Collection&, const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredCollectionUnsubscribed( const Akonadi::Collection& ) )

    Q_PRIVATE_SLOT( d_func(), void monitoredItemAdded( const Akonadi::Item&, const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemRemoved( const Akonadi::Item& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemChanged( const Akonadi::Item&, const QSet<QByteArray>& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemMoved( const Akonadi::Item&, const Akonadi::Collection&,
                                                       const Akonadi::Collection& ) )

    Q_PRIVATE_SLOT( d_func(), void monitoredItemLinked( const Akonadi::Item&, const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemUnlinked( const Akonadi::Item&, const Akonadi::Collection& ) )
    Q_PRIVATE_SLOT( d_func(), void changeFetchState( const Akonadi::Collection & ) )

    Q_PRIVATE_SLOT( d_func(), void agentInstanceAdvancedStatusChanged( const QString&, const QVariantMap& ) )
    Q_PRIVATE_SLOT( d_func(), void agentInstanceRemoved( Akonadi::AgentInstance ) )
    Q_PRIVATE_SLOT( d_func(), void monitoredItemsRetrieved(KJob* job) )
    //@endcond
};

} // namespace

#endif