kget/core/transferhandler.h

   1 /* This file is part of the KDE project
   2
   3    Copyright (C) 2005 Dario Massarin <nekkar@libero.it>
   4
   5    This program is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9 */
  10
  11
  12 #ifndef TRANSFERHANDLER_H
  13 #define TRANSFERHANDLER_H
  14
  15 #include <QVariant>
  16
  17 #include "transfer.h"
  18 #include "transfergroup.h"
  19 #include "kget_export.h"
  20
  21 class KMenu;
  22
  23
  24 class TransferObserver;
  25
  26 /**
  27  * Class TransferHandler:
  28  *
  29  * --- Overview ---
  30  * This class is the rapresentation of a Transfer object from the views'
  31  * perspective (proxy pattern). In fact the views never handle directly the
  32  * Transfer objects themselves (because this would break the model/view policy).
  33  * As a general rule, all the code strictly related to the views should placed
  34  * here (and not in the transfer implementation).
  35  * Here we provide the same api available in the transfer class, but we change
  36  * the implementation of some methods.
  37  * Let's give an example about this:
  38  * The start() function of a specific Transfer (let's say TransferKio) is a
  39  * low level command that really makes the transfer start and should therefore
  40  * be executed only by the scheduler.
  41  * The start() function in this class is implemented in another way, since
  42  * it requests the scheduler to execute the start command to this specific transfer.
  43  * At this point the scheduler will evaluate this request and execute, if possible,
  44  * the start() function directly in the TransferKio.
  45  *
  46  * --- Notifies about the transfer changes ---
  47  * When a view is interested in receiving notifies about the specific transfer
  48  * rapresented by this TransferHandler object, it should add itself to the list
  49  * of observers calling the addObserver(TransferObserver *) function. On the
  50  * contrary call the delObserver(TransferObserver *) function to remove it.
  51  *
  52  * --- Interrogation about what has changed in the transfer ---
  53  * When a TransferObserver receives a notify about a change in the Transfer, it
  54  * can ask to the TransferHandler for the ChangesFlags.
  55  */
  56
  57 class KGET_EXPORT TransferHandler
  58 {
  59     friend class KGet;
  60     friend class TransferTreeModel;
  61     friend class Transfer;
  62     friend class TransferFactory;
  63     friend class TransferGroupHandler;
  64
  65     public:
  66
  67         typedef Transfer::ChangesFlags ChangesFlags;
  68
  69         TransferHandler(Transfer * transfer, Scheduler * scheduler);
  70
  71         virtual ~TransferHandler();
  72
  73         /**
  74          * Adds an observer to this Transfer
  75          *
  76          * @param observer Tthe new observer that should be added
  77          */
  78         void addObserver(TransferObserver * observer);
  79
  80         /**
  81          * Removes an observer from this Transfer
  82          *
  83          * @param observer The observer that should be removed
  84          */
  85         void delObserver(TransferObserver * observer);
  86
  87         /**
  88          * These are all Job-related functions
  89          */
  90         void start();
  91         void stop();
  92         void setDelay(int seconds);
  93         Job::Status status() const {return m_transfer->status();}
  94         int elapsedTime() const;
  95         int remainingTime() const;
  96         bool isResumable() const;
  97
  98         /**
  99          * @return the transfer's group handler
 100          */
 101         TransferGroupHandler * group() const {return m_transfer->group()->handler();}
 102
 103         /**
 104          * @return the source url
 105          */
 106         const KUrl & source() const {return m_transfer->source();}
 107
 108         /**
 109          * @return the dest url
 110          */
 111         const KUrl & dest() const {return m_transfer->dest();}
 112
 113         /**
 114          * @return the total size of the transfer in bytes
 115          */
 116         unsigned long totalSize() const;
 117
 118         /**
 119          * @return the downloaded size of the transfer in bytes
 120          */
 121         unsigned long processedSize() const;
 122
 123         /**
 124          * @return the progress percentage of the transfer
 125          */
 126         int percent() const;
 127
 128         /**
 129          * @return the download speed of the transfer in bytes/sec
 130          */
 131         int speed() const;
 132
 133         /**
 134          * @return a string describing the current transfer status
 135          */
 136         QString statusText() const {return m_transfer->statusText();}
 137
 138         /**
 139          * @return a pixmap associated with the current transfer status
 140          */
 141         QPixmap statusPixmap() const {return m_transfer->statusPixmap();}
 142
 143         /**
 144          * @returns the data associated to this Transfer item. This is
 145          * necessary to make the interview model/view work
 146          */
 147         QVariant data(int column);
 148
 149         /**
 150          * @returns the number of columns associated to the transfer's data
 151          */
 152         int columnCount() const     {return 5;}
 153
 154         /**
 155          * Returns a KMenu for the given list of transfers, populated with
 156          * the actions that can be executed on each transfer in the list.
 157          * If the list is null, it returns the KMenu associated with the
 158          * this transfer.
 159          *
 160          * @param transfers the transfer list
 161          *
 162          * @return a KMenu for the given transfers
 163          */
 164         KMenu * popupMenu(QList<TransferHandler *> transfers);
 165
 166         /**
 167          * Selects the current transfer. Selecting transfers means that all
 168          * the actions executed from the gui will apply also to the current
 169          * transfer.
 170          *
 171          * @param select if true the current transfer is selected
 172          *               if false the current transfer is deselected
 173          */
 174         void setSelected( bool select );
 175
 176         /**
 177          * @returns true if the current transfer is selected
 178          * @returns false otherwise
 179          */
 180         bool isSelected() const;
 181
 182         /**
 183          * Returns the changes flags
 184          *
 185          * @param observer The observer that makes this request
 186          */
 187         ChangesFlags changesFlags(TransferObserver * observer) const;
 188
 189         /**
 190          * Resets the changes flags for a given TransferObserver
 191          *
 192          * @param observer The observer that makes this request
 193          */
 194         void resetChangesFlags(TransferObserver * observer);
 195
 196     private:
 197         /**
 198          * Sets a change flag in the ChangesFlags variable.
 199          *
 200          * @param change The TransferChange flag to be set
 201          * @param postEvent if false the handler will not post an event to the observers,
 202          * if true the handler will post an event to the observers
 203          */
 204         void setTransferChange(ChangesFlags change, bool postEvent=false);
 205
 206         /**
 207          * Posts a TransferChangedEvent to all the observers.
 208          */
 209         void postTransferChangedEvent();
 210
 211         /**
 212          * Posts a deleteEvent to all the observers
 213          */
 214         void postDeleteEvent();
 215
 216         Transfer * m_transfer;
 217         Scheduler * m_scheduler;
 218
 219         QList<TransferObserver *> m_observers;
 220         QMap<TransferObserver *, ChangesFlags> m_changesFlags;
 221 };
 222
 223 #endif