mobile/lib/kdeclarativemainview.h

   1 /*
   2     Copyright (c) 2010 Bertjan Broeksema <broeksema@kde.org>
   3
   4     This library is free software; you can redistribute it and/or modify it
   5     under the terms of the GNU Library General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or (at your
   7     option) any later version.
   8
   9     This library is distributed in the hope that it will be useful, but WITHOUT
  10     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  12     License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to the
  16     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17     02110-1301, USA.
  18 */
  19 #ifndef KDECLARATIVEMAINVIEW_H
  20 #define KDECLARATIVEMAINVIEW_H
  21
  22 #include "kdeclarativefullscreenview.h"
  23
  24 #include <QtGui/QItemSelectionModel>
  25
  26 class ExportHandlerBase;
  27 class GuiStateManager;
  28 class ImportHandlerBase;
  29 class KLineEdit;
  30 class ListProxy;
  31 class QAbstractItemModel;
  32 class QAbstractProxyModel;
  33
  34 namespace Akonadi {
  35 class AgentActionManager;
  36 class ChangeRecorder;
  37 class EntityTreeModel;
  38 class Item;
  39 class ItemFetchScope;
  40 }
  41
  42 class KDeclarativeMainViewPrivate;
  43
  44 /**
  45  * Main view for mobile applications. This class is just to share code and therefore
  46  * should not be instantiated by itself.
  47  */
  48 class MOBILEUI_EXPORT KDeclarativeMainView : public KDeclarativeFullScreenView
  49 {
  50     Q_OBJECT
  51     Q_PROPERTY( int numSelectedAccounts READ numSelectedAccounts NOTIFY numSelectedAccountsChanged )
  52     Q_PROPERTY( bool isLoadingSelected READ isLoadingSelected NOTIFY isLoadingSelectedChanged )
  53     Q_PROPERTY( QString version READ version CONSTANT )
  54     Q_PROPERTY( QString name READ name CONSTANT )
  55     Q_PROPERTY( QString state READ applicationState WRITE setApplicationState NOTIFY stateChanged )
  56
  57   public:
  58     /**
  59      * Destroys the declarative main view.
  60      */
  61     virtual ~KDeclarativeMainView();
  62
  63     /**
  64      * Item fetch scope to specify how much data should be loaded for the list view.
  65      * By default nothing is loaded.
  66      */
  67     Akonadi::ItemFetchScope& itemFetchScope();
  68
  69     /**
  70      * Adds a mime type of the items handled by this application.
  71      */
  72     void addMimeType( const QString &mimeType );
  73
  74     /**
  75      * Returns the mime types of the items handled by this application.
  76      */
  77     QStringList mimeTypes() const;
  78
  79     /**
  80      * Returns the number of selected accounts.
  81      */
  82     int numSelectedAccounts();
  83
  84     /**
  85      * Returns the version of the application.
  86      */
  87     QString version() const;
  88
  89     /**
  90      * Returns the localized name of the application.
  91      */
  92     QString name() const;
  93
  94     /**
  95      * Returns the monitor that is used by the application.
  96      */
  97     Akonadi::ChangeRecorder* monitor() const;
  98
  99     /**
 100      * Returns the gui state manager that will be used to manage the visibility
 101      * of the various gui elements of the application.
 102      */
 103     GuiStateManager* guiStateManager() const;
 104
 105     /**
 106      * Sets the @p lineEdit that is used to filter the items in the listview.
 107      */
 108     void setFilterLineEdit( KLineEdit *lineEdit );
 109
 110     /**
 111      * Sets the @p lineEdit that is used to filter the items in the listview in bulk action mode.
 112      */
 113     void setBulkActionFilterLineEdit( KLineEdit *lineEdit );
 114
 115     QString applicationState() const;
 116     void setApplicationState( const QString &state );
 117
 118   public slots:
 119     void setSelectedAccount( int row );
 120
 121     void setAgentInstanceListSelectedRow( int row );
 122
 123     /**
 124      * Starts the account wizard to add and configure new resources.
 125      */
 126     void launchAccountWizard();
 127
 128     /**
 129      * Starts the synchronization of all collections.
 130      */
 131     void synchronizeAllItems();
 132
 133     /**
 134      * Opens the licenses.pdf in an external viewer
 135      */
 136     void openLicenses();
 137
 138     void saveFavorite();
 139     void loadFavorite( const QString &name );
 140     void multipleSelectionFinished();
 141
 142     void persistCurrentSelection( const QString &key );
 143     void clearPersistedSelection( const QString &key );
 144     void restorePersistedSelection( const QString &key );
 145
 146     /**
 147      * Starts the import of items to the application.
 148      *
 149      * The actual work is done by the ImportHandlerBase objects returned
 150      * by the importHandler() method.
 151      */
 152     void importItems();
 153
 154     /**
 155      * Starts the export of items from the application.
 156      *
 157      * The actual work is done by the ExportHandlerBase objects returned
 158      * by the exportHandler() method.
 159      */
 160     void exportItems();
 161
 162     /**
 163      * Starts the export of a single item from the application.
 164      *
 165      * The actual work is done by the ExportHandlerBase objects returned
 166      * by the exportHandler() method.
 167      */
 168     void exportSingleItem();
 169
 170     /**
 171      * Opens the user manual of this application in an external web browser.
 172      */
 173     void openManual();
 174
 175     /**
 176      * Opens the HTML based documentation located at the given relative @p path.
 177      */
 178     void openDocumentation( const QString &path );
 179
 180     void openAttachment( const QString &url, const QString &mimeType );
 181     void saveAttachment( const QString &url, const QString &defaultFileName = QString() );
 182
 183     void reportBug();
 184
 185     void checkAllBulkActionItems( bool select );
 186
 187   Q_SIGNALS:
 188     void numSelectedAccountsChanged();
 189     void isLoadingSelectedChanged();
 190     void stateChanged();
 191
 192     /**
 193      * This signal is emitted whenever the collection has been changed but
 194      * before the item list is updated.
 195      */
 196     void collectionSelectionChanged();
 197
 198   protected:
 199     /**
 200      * Creates a new main view for a mobile application.
 201      *
 202      * @param appName is used to find the QML file in ${DATA_DIR}/mobile/appname.qml
 203      * @param listProxy proxy for the list view of the application. KDeclarativeMainView
 204      *                  takes ownwership over the pointer.
 205      * @param parent The parent widget.
 206      */
 207     KDeclarativeMainView( const QString &appName, ListProxy *listProxy, QWidget *parent = 0 );
 208
 209     /**
 210      * Returns the global entity tree model.
 211      */
 212     Akonadi::EntityTreeModel* entityTreeModel() const;
 213
 214     /**
 215      * Returns the filtered and QML-adapted item model.
 216      */
 217     QAbstractItemModel* itemModel() const;
 218
 219     /**
 220      * Returns whether the currently selected item is being loaded.
 221      * Note that results appear asynchronously in chunks while loading the contents
 222      * of a collection. That means that the number of items can be greater then zero
 223      * while isLoadingSelected returns true.
 224      */
 225     bool isLoadingSelected();
 226
 227     /**
 228      * Initializes the standard action manager that will be used by the application.
 229      * This is a point of extension to use a custom action manager.
 230      *
 231      * @param collectionSelectionModel The selection model for the collections.
 232      * @param itemSelectionModel The selection model for the items.
 233      */
 234     virtual void setupStandardActionManager( QItemSelectionModel *collectionSelectionModel,
 235                                              QItemSelectionModel *itemSelectionModel );
 236
 237     /**
 238      * Initializes the agent action manager that will be used by the application.
 239      * This is a point of extension to use a custom action manager.
 240      *
 241      * @param selectionModel The selection model for the agent instances.
 242      */
 243     virtual void setupAgentActionManager( QItemSelectionModel *selectionModel ) = 0;
 244
 245     /**
 246      * Returns the a proxy model that will be used on top of the entity tree model.
 247      */
 248     virtual QAbstractProxyModel* createMainProxyModel() const;
 249
 250     /**
 251      * Returns the filter proxy model that will be used to filter the item list.
 252      * If @c 0 is returned, no filtering is done.
 253      *
 254      * @note The model has to provide a public slot with the following signature:
 255      *       void setFilterString( const QString& )
 256      */
 257     virtual QAbstractProxyModel* createItemFilterModel() const;
 258
 259     /**
 260      * Set the filter proxy model that will be used to filter the item list.
 261      * Call this when calling createItemFilterModel() manually in your code.
 262      */
 263     void setItemFilterModel( QAbstractProxyModel* model );
 264
 265     /**
 266      * Returns the object that will be used for importing data.
 267      * If @c 0 is returned, no import functionality is offered.
 268      */
 269     virtual ImportHandlerBase* importHandler() const;
 270
 271     /**
 272      * Returns the object that will be used for exporting data.
 273      * If @c 0 is returned, no export functionality is offered.
 274      */
 275     virtual ExportHandlerBase* exportHandler() const;
 276
 277     /**
 278      * Returns the gui state manager that will be used by the application.
 279      *
 280      * Subclasses should returns its custom gui state managers here.
 281      */
 282     virtual GuiStateManager* createGuiStateManager() const;
 283
 284     /**
 285      * This method is called when a single @p item has been selected to view.
 286      */
 287     virtual void viewSingleItem( const Akonadi::Item &item );
 288
 289     /**
 290      * Returns whether the application is in a state where the filter line edit
 291      * can be used.
 292      */
 293     virtual bool useFilterLineEditInCurrentState() const;
 294
 295     /**
 296      * Returns whether the application is in a state where the filter line edit
 297      * must not be used.
 298      */
 299     virtual bool doNotUseFilterLineEditInCurrentState() const;
 300
 301   protected Q_SLOTS:
 302     void breadcrumbsSelectionChanged();
 303     void itemSelectionChanged();
 304
 305   protected:
 306     /**
 307      * The selection model that belongs to the item model returned by entityTreeModel()
 308      * or to the one returned by createMainProxyModel().
 309      */
 310     QItemSelectionModel* regularSelectionModel() const;
 311
 312     /**
 313      * The selection model which provides the information about checked
 314      * items in the bulk action screen.
 315      */
 316     QItemSelectionModel* itemActionModel() const;
 317
 318     QAbstractProxyModel* itemFilterModel() const;
 319     QAbstractProxyModel* listProxy() const;
 320     QItemSelectionModel* itemSelectionModel() const;
 321     QAbstractItemModel* selectedItemsModel() const;
 322
 323     Akonadi::Item itemFromId( quint64 id ) const;
 324
 325     virtual void keyPressEvent( QKeyEvent *event );
 326
 327     virtual QAbstractItemModel* createItemModelContext( QDeclarativeContext *context, QAbstractItemModel *model );
 328     void setItemNaigationAndActionSelectionModels( QItemSelectionModel *itemNavigationSelectionModel, QItemSelectionModel *itemActionSelectionModel );
 329
 330     /**
 331      * Returns a newly created AgentActionMananger with standard setup.
 332      * Use inside setupAgentActionManager();
 333      */
 334     Akonadi::AgentActionManager *createAgentActionManager( QItemSelectionModel* agentSelectionModel );
 335
 336   private:
 337     void doDelayedInitInternal();
 338     KDeclarativeMainViewPrivate * const d;
 339
 340     Q_PRIVATE_SLOT( d, void filterLineEditChanged( const QString& ) )
 341     Q_PRIVATE_SLOT( d, void bulkActionFilterLineEditChanged( const QString& ) )
 342 };
 343
 344 #endif // KDECLARATIVEMAINVIEW_H