libkdepim/progressmanager.h

   1 /*
   2   progressmanager.h
   3
   4   This file is part of libkdepim.
   5
   6   Copyright (C) 2004 Till Adam <adam@kde.org>
   7
   8   This library is free software; you can redistribute it and/or
   9   modify it under the terms of the GNU Library General Public
  10   License as published by the Free Software Foundation; either
  11   version 2 of the License, or (at your option) any later version.
  12
  13   This library is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16   Library General Public License for more details.
  17
  18   You should have received a copy of the GNU Library General Public License
  19   along with this library; see the file COPYING.LIB.  If not, write to
  20   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21   Boston, MA 02110-1301, USA.
  22 */
  23
  24 #ifndef KDEPIM_PROGRESSMANAGER_H
  25 #define KDEPIM_PROGRESSMANAGER_H
  26
  27 #include "kdepim_export.h"
  28
  29 #include <QObject>
  30 #include <QString>
  31 #include <QMap>
  32 #include <QHash>
  33 #include <QWeakPointer>
  34 #include <QPointer>
  35 namespace Akonadi {
  36   class AgentInstance;
  37 }
  38
  39 namespace KPIM {
  40
  41 class ProgressItem;
  42 class ProgressManager;
  43 typedef QMap<ProgressItem *, bool> ProgressItemMap;
  44
  45 class KDEPIM_EXPORT ProgressItem : public QObject
  46 {
  47   Q_OBJECT
  48   friend class ProgressManager;
  49
  50   public:
  51
  52     /**
  53      * @return The id string which uniquely identifies the operation
  54      *         represented by this item.
  55      */
  56     const QString &id() const { return mId; }
  57
  58     /**
  59      * @return The parent item of this one, if there is one.
  60      */
  61     ProgressItem *parent() const { return mParent.data(); }
  62
  63     /**
  64      * @return The user visible string to be used to represent this item.
  65      */
  66     const QString &label() const { return mLabel; }
  67
  68     /**
  69      * @param v Set the user visible string identifying this item.
  70      */
  71     void setLabel( const QString &v );
  72
  73     /**
  74      * @return The string to be used for showing this item's current status.
  75      */
  76     const QString &status() const { return mStatus; }
  77     /**
  78      * Set the string to be used for showing this item's current status.
  79      * @param v The status string.
  80      */
  81     void setStatus( const QString &v );
  82
  83     /**
  84      * @return Whether this item can be canceled.
  85      */
  86     bool canBeCanceled() const { return mCanBeCanceled; }
  87
  88     /**
  89      * @return Whether this item uses secure communication
  90      * (Account uses ssl, for example.).
  91      */
  92     bool usesCrypto() const { return mUsesCrypto; }
  93
  94     /**
  95      * Set whether this item uses crypted communication, so listeners
  96      * can display a nice crypto icon.
  97      * @param v The value.
  98      */
  99     void setUsesCrypto( bool v );
 100
 101     /**
 102      * @return whether this item uses a busy indicator instead of real progress display
 103      */
 104     bool usesBusyIndicator() const { return mUsesBusyIndicator; }
 105
 106     /**
 107      * Sets whether this item uses a busy indicator instead of real progress for its progress bar.
 108      * If it uses a busy indicator, you are still responsible for calling setProgress() from time to
 109      * time to update the busy indicator.
 110      */
 111     void setUsesBusyIndicator( bool useBusyIndicator );
 112
 113     /**
 114      * @return The current progress value of this item in percent.
 115      */
 116     unsigned int progress() const { return mProgress; }
 117
 118     /**
 119      * Set the progress (percentage of completion) value of this item.
 120      * @param v The percentage value.
 121      */
 122     void setProgress( unsigned int v );
 123
 124     /**
 125      * Tell the item it has finished. This will emit progressItemCompleted()
 126      * result in the destruction of the item after all slots connected to this
 127      * signal have executed. This is the only way to get rid of an item and
 128      * needs to be called even if the item is canceled. Don't use the item
 129      * after this has been called on it.
 130      */
 131     void setComplete();
 132
 133     /**
 134      * Reset the progress value of this item to 0 and the status string to
 135      * the empty string.
 136      */
 137     void reset()
 138     {
 139       setProgress( 0 );
 140       setStatus( QString() );
 141       mCompleted = 0;
 142     }
 143
 144     void cancel();
 145
 146     // Often needed values for calculating progress.
 147     void setTotalItems( unsigned int v ) { mTotal = v; }
 148     unsigned int totalItems() const { return mTotal; }
 149     void setCompletedItems( unsigned int v ) { mCompleted = v; }
 150     void incCompletedItems( unsigned int v = 1 ) { mCompleted += v; }
 151     unsigned int completedItems() const { return mCompleted; }
 152
 153     /**
 154      * Recalculate progress according to total/completed items and update.
 155      */
 156     void updateProgress()
 157     {
 158       setProgress( mTotal? mCompleted * 100 / mTotal : 0 );
 159     }
 160
 161     void addChild( ProgressItem *kiddo );
 162     void removeChild( ProgressItem *kiddo );
 163
 164     bool canceled() const { return mCanceled; }
 165
 166   Q_SIGNALS:
 167     /**
 168      * Emitted when a new ProgressItem is added.
 169      * @param The ProgressItem that was added.
 170      */
 171     void progressItemAdded( KPIM::ProgressItem * );
 172
 173     /**
 174      * Emitted when the progress value of an item changes.
 175      * @param  The item which got a new value.
 176      * @param  The value, for convenience.
 177      */
 178     void progressItemProgress( KPIM::ProgressItem *, unsigned int );
 179
 180     /**
 181      * Emitted when a progress item was completed. The item will be
 182      * deleted afterwards, so slots connected to this are the last
 183      * chance to work with this item.
 184      * @param The completed item.
 185      */
 186     void progressItemCompleted( KPIM::ProgressItem * );
 187
 188     /**
 189      * Emitted when an item was canceled. It will _not_ go away immediately,
 190      * only when the owner sets it complete, which will usually happen. Can be
 191      * used to visually indicate the canceled status of an item. Should be used
 192      * by the owner of the item to make sure it is set completed even if it is
 193      * canceled. There is a ProgressManager::slotStandardCancelHandler which
 194      * simply sets the item completed and can be used if no other work needs to
 195      * be done on cancel.
 196      * @param The canceled item;
 197      */
 198     void progressItemCanceled( KPIM::ProgressItem * );
 199
 200     /**
 201      * Emitted when the status message of an item changed. Should be used by
 202      * progress dialogs to update the status message for an item.
 203      * @param  The updated item.
 204      * @param  The new message.
 205      */
 206     void progressItemStatus( KPIM::ProgressItem *, const QString & );
 207
 208     /**
 209      * Emitted when the label of an item changed. Should be used by
 210      * progress dialogs to update the label of an item.
 211      * @param  The updated item.
 212      * @param  The new label.
 213      */
 214     void progressItemLabel( KPIM::ProgressItem *, const QString & );
 215
 216     /**
 217      * Emitted when the crypto status of an item changed. Should be used by
 218      * progress dialogs to update the crypto indicator of an item.
 219      * @param  The updated item.
 220      * @param  The new state.
 221      */
 222     void progressItemUsesCrypto( KPIM::ProgressItem *, bool );
 223
 224     /**
 225      * Emitted when the busy indicator state of an item changes. Should be used
 226      * by progress dialogs so that they can adjust the display of the progress bar
 227      * to the new mode.
 228      * @param item The updated item
 229      * @param value True if the item uses a busy indicator now, false otherwise
 230      */
 231     void progressItemUsesBusyIndicator( KPIM::ProgressItem *item, bool value );
 232
 233   protected:
 234     /* Only to be used by our good friend the ProgressManager */
 235     ProgressItem( ProgressItem *parent, const QString &id, const QString &label,
 236                   const QString &status, bool isCancellable, bool usesCrypto );
 237     virtual ~ProgressItem();
 238
 239   private:
 240     QString mId;
 241     QString mLabel;
 242     QString mStatus;
 243     QWeakPointer<ProgressItem>mParent;
 244     bool mCanBeCanceled;
 245     unsigned int mProgress;
 246     ProgressItemMap mChildren;
 247     unsigned int mTotal;
 248     unsigned int mCompleted;
 249     bool mWaitingForKids;
 250     bool mCanceled;
 251     bool mUsesCrypto;
 252     bool mUsesBusyIndicator;
 253     bool mCompletedCalled;
 254 };
 255
 256 struct ProgressManagerPrivate;
 257
 258 /**
 259  * The ProgressManager singleton keeps track of all ongoing transactions
 260  * and notifies observers (progress dialogs) when their progress percent value
 261  * changes, when they are completed (by their owner), and when they are canceled.
 262  * Each ProgressItem emits those signals individually and the singleton
 263  * broadcasts them. Use the ::createProgressItem() statics to acquire an item
 264  * and then call ->setProgress( int percent ) on it every time you want to
 265  * update the item and ->setComplete() when the operation is done. This will
 266  * delete the item. Connect to the item's progressItemCanceled() signal to be
 267  * notified when the user cancels the transaction using one of the observing
 268  * progress dialogs or by calling item->cancel() in some other way. The owner
 269  * is responsible for calling setComplete() on the item, even if it is canceled.
 270  * Use the standardCancelHandler() slot if that is all you want to do on cancel.
 271  *
 272  * Note that if you request an item with a certain id and there is already
 273  * one with that id, there will not be a new one created but the existing
 274  * one will be returned. This is convenient for accessing items that are
 275  * needed regularly without the to store a pointer to them or to add child
 276  * items to parents by id.
 277  */
 278 class KDEPIM_EXPORT ProgressManager : public QObject
 279 {
 280
 281   Q_OBJECT
 282
 283   friend struct ProgressManagerPrivate;
 284
 285   public:
 286     virtual ~ProgressManager();
 287
 288     /**
 289      * @return The singleton instance of this class.
 290      */
 291     static ProgressManager *instance();
 292
 293     /**
 294      * Use this to acquire a unique id number which can be used to discern
 295      * an operation from all others going on at the same time. Use that
 296      * number as the id string for your progressItem to ensure it is unique.
 297      * @return
 298      */
 299     static QString getUniqueID()
 300     {
 301       return QString::number( ++uID );
 302     }
 303
 304      /**
 305       * Creates a ProgressItem with a unique id and the given label.
 306       * This is the simplest way to acquire a progress item. It will not
 307       * have a parent and will be set to be cancellable and not using crypto.
 308       */
 309     static ProgressItem *createProgressItem( const QString &label )
 310     {
 311       return instance()->createProgressItemImpl( 0, getUniqueID(), label,
 312                                                  QString(), true, false );
 313     }
 314
 315     /**
 316      * Creates a new progressItem with the given parent, id, label and initial
 317      * status.
 318      *
 319      * @param parent Specify an already existing item as the parent of this one.
 320      * @param id Used to identify this operation for cancel and progress info.
 321      * @param label The text to be displayed by progress handlers
 322      * @param status Additional text to be displayed for the item.
 323      * @param canBeCanceled can the user cancel this operation?
 324      * @param usesCrypto does the operation use secure transports (SSL)
 325      * Cancelling the parent will cancel the children as well (if they can be
 326      * canceled) and ongoing children prevent parents from finishing.
 327      * @return The ProgressItem representing the operation.
 328      */
 329     static ProgressItem *createProgressItem( ProgressItem *parent,
 330                                              const QString &id,
 331                                              const QString &label,
 332                                              const QString &status = QString(),
 333                                              bool canBeCanceled = true,
 334                                              bool usesCrypto = false )
 335     {
 336       return instance()->createProgressItemImpl( parent, id, label, status,
 337                                                  canBeCanceled, usesCrypto );
 338     }
 339
 340     /**
 341      * Use this version if you have the id string of the parent and want to
 342      * add a subjob to it.
 343      */
 344     static ProgressItem *createProgressItem( const QString &parent,
 345                                              const QString &id,
 346                                              const QString &label,
 347                                              const QString &status = QString(),
 348                                              bool canBeCanceled = true,
 349                                              bool usesCrypto = false )
 350     {
 351       return instance()->createProgressItemImpl( parent, id, label,
 352                                                  status, canBeCanceled, usesCrypto );
 353     }
 354
 355     /**
 356      * Version without a parent.
 357      */
 358     static ProgressItem *createProgressItem( const QString &id,
 359                                              const QString &label,
 360                                              const QString &status = QString(),
 361                                              bool canBeCanceled = true,
 362                                              bool usesCrypto = false )
 363     {
 364       return instance()->createProgressItemImpl( 0, id, label, status,
 365                                                  canBeCanceled, usesCrypto );
 366     }
 367
 368     /**
 369      * Version for Akonadi agents.
 370      * This connects all the proper signals so that you do not have to
 371      * worry about updating the progress or reacting to progressItemCanceled().
 372      */
 373     static ProgressItem *createProgressItem( ProgressItem *parent,
 374                                              const Akonadi::AgentInstance &agent,
 375                                              const QString &id,
 376                                              const QString &label,
 377                                              const QString &status = QString(),
 378                                              bool canBeCanceled = true,
 379                                              bool usesCrypto = false )
 380     {
 381       return instance()->createProgressItemForAgent( parent, agent, id, label,
 382                                                      status, canBeCanceled, usesCrypto );
 383     }
 384
 385     /**
 386      * @return true when there are no more progress items.
 387      */
 388     bool isEmpty() const
 389     {
 390       return mTransactions.isEmpty();
 391     }
 392
 393     /**
 394      * @return the only top level progressitem when there's only one.
 395      * Returns 0 if there is no item, or more than one top level item.
 396      * Since this is used to calculate the overall progress, it will also return
 397      * 0 if there is an item which uses a busy indicator, since that will invalidate
 398      * the overall progress.
 399      */
 400     ProgressItem *singleItem() const;
 401
 402     /**
 403      * Ask all listeners to show the progress dialog, because there is
 404      * something that wants to be shown.
 405      */
 406     static void emitShowProgressDialog()
 407     {
 408        instance()->emitShowProgressDialogImpl();
 409     }
 410
 411   Q_SIGNALS:
 412     /** @see ProgressItem::progressItemAdded() */
 413     void progressItemAdded( KPIM::ProgressItem * );
 414     /** @see ProgressItem::progressItemProgress() */
 415     void progressItemProgress( KPIM::ProgressItem *, unsigned int );
 416     /** @see ProgressItem::progressItemCompleted() */
 417     void progressItemCompleted( KPIM::ProgressItem * );
 418     /** @see ProgressItem::progressItemCanceled() */
 419     void progressItemCanceled( KPIM::ProgressItem * );
 420     /** @see ProgressItem::progressItemStatus() */
 421     void progressItemStatus( KPIM::ProgressItem *, const QString & );
 422     /** @see ProgressItem::progressItemLabel() */
 423     void progressItemLabel( KPIM::ProgressItem *, const QString & );
 424     /** @see ProgressItem::progressItemUsesCrypto() */
 425     void progressItemUsesCrypto( KPIM::ProgressItem *, bool );
 426     /** @see ProgressItem::progressItemUsesBusyIndicator */
 427     void progressItemUsesBusyIndicator( KPIM::ProgressItem*, bool );
 428
 429     /**
 430      * Emitted when an operation requests the listeners to be shown.
 431      * Use emitShowProgressDialog() to trigger it.
 432      */
 433     void showProgressDialog();
 434
 435   public Q_SLOTS:
 436
 437     /**
 438      * Calls setCompleted() on the item, to make sure it goes away.
 439      * Provided for convenience.
 440      * @param item the canceled item.
 441      */
 442     void slotStandardCancelHandler( KPIM::ProgressItem *item );
 443
 444     /**
 445      * Aborts all running jobs. Bound to "Esc"
 446      */
 447     void slotAbortAll();
 448
 449   private Q_SLOTS:
 450     void slotTransactionCompleted( KPIM::ProgressItem *item );
 451
 452   private:
 453     ProgressManager();
 454      // prevent unsolicited copies
 455     ProgressManager( const ProgressManager & );
 456
 457     virtual ProgressItem *createProgressItemImpl( ProgressItem *parent,
 458                                                   const QString &id,
 459                                                   const QString &label,
 460                                                   const QString &status,
 461                                                   bool cancellable,
 462                                                   bool usesCrypto );
 463     virtual ProgressItem *createProgressItemImpl( const QString &parent,
 464                                                   const QString &id,
 465                                                   const QString &label,
 466                                                   const QString &status,
 467                                                   bool cancellable,
 468                                                   bool usesCrypto );
 469     ProgressItem *createProgressItemForAgent( ProgressItem *parent,
 470                                               const Akonadi::AgentInstance &instance,
 471                                               const QString &id,
 472                                               const QString &label,
 473                                               const QString &status,
 474                                               bool cancellable,
 475                                               bool usesCrypto );
 476     void emitShowProgressDialogImpl();
 477
 478     QHash< QString, ProgressItem* > mTransactions;
 479     static unsigned int uID;
 480 };
 481
 482 }
 483
 484 #endif // __KPIM_PROGRESSMANAGER_H__