akregator/src/treenode.h

   1 /*
   2     This file is part of Akregator.
   3
   4     Copyright (C) 2004 Frank Osterfeld <osterfeld@kde.org>
   5
   6     This program is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10
  11     This program is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with this program; if not, write to the Free Software
  18     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19
  20     As a special exception, permission is given to link this program
  21     with any edition of Qt, and distribute the resulting executable,
  22     without including the source code for Qt in the source distribution.
  23 */
  24
  25 #ifndef AKREGATOR_TREENODE_H
  26 #define AKREGATOR_TREENODE_H
  27
  28 #include "akregator_export.h"
  29 #include <QObject>
  30 #include <QVector>
  31
  32 class KJob;
  33
  34 class QDomDocument;
  35 class QDomElement;
  36 class QIcon;
  37 class QPoint;
  38 class QString;
  39 class QStringList;
  40 template <class T> class QList;
  41
  42 namespace Akregator
  43 {
  44
  45 class ArticleListJob;
  46 class TreeNodeVisitor;
  47 class Article;
  48 class Feed;
  49 class Folder;
  50 class FetchQueue;
  51
  52 /**
  53     \brief Abstract base class for all kind of elements in the feed tree, like feeds and feed groups (and search folders later).
  54
  55     TODO: detailed description goes here
  56 */
  57 class AKREGATOR_EXPORT TreeNode : public QObject
  58 {
  59     friend class ::Akregator::ArticleListJob;
  60     friend class ::Akregator::Folder;
  61
  62     Q_OBJECT
  63
  64 public:
  65
  66     /** Standard constructor */
  67     TreeNode();
  68
  69     /** Standard destructor */
  70     virtual ~TreeNode();
  71
  72     virtual bool accept(TreeNodeVisitor *visitor) = 0;
  73
  74     /** The unread count, returns the number of new/unread articles in the node (for groups: the accumulated count of the subtree)
  75     @return number of new/unread articles */
  76
  77     virtual int unread() const = 0;
  78
  79     /** returns the number of total articles in the node (for groups: the accumulated count of the subtree)
  80     @return number of articles */
  81
  82     virtual int totalCount() const = 0;
  83
  84     /** Get title of node.
  85     @return the title of the node */
  86
  87     QString title() const;
  88
  89     /** Sets the title of the node.
  90     @c title should not contain entities.
  91     @param title the title string */
  92
  93     void setTitle(const QString &title);
  94
  95     /** Get the next sibling.
  96     @return the next sibling, 0 if there is none */
  97
  98     virtual const TreeNode *nextSibling() const;
  99     virtual TreeNode *nextSibling();
 100
 101     /** Get the previous sibling.
 102     @return the previous sibling, 0 if there is none */
 103
 104     virtual const TreeNode *prevSibling() const;
 105     virtual TreeNode *prevSibling();
 106
 107     /** Returns the parent node.
 108     @return the parent feed group, 0 if there is none */
 109
 110     virtual const Folder *parent() const;
 111     virtual Folder *parent();
 112
 113     /** returns the (direct) children of this node.
 114         @return a list of pointers to the child nodes
 115      */
 116     virtual QList<const TreeNode *> children() const;
 117     virtual QList<TreeNode *> children();
 118
 119     virtual QVector<const Feed *> feeds() const = 0;
 120     virtual QVector<Feed *> feeds() = 0;
 121
 122     virtual QVector<const Folder *> folders() const = 0;
 123     virtual QVector<Folder *> folders() = 0;
 124
 125     virtual TreeNode *childAt(int pos);
 126     virtual const TreeNode *childAt(int pos) const;
 127
 128     /** Sets parent node; Don't call this directly, is done automatically by
 129     insertChild-methods in @ref Folder. */
 130
 131     virtual void setParent(Folder *parent);
 132
 133     virtual QIcon icon() const = 0;
 134
 135     ArticleListJob *createListJob();
 136
 137     /** Helps the rest of the app to decide if node should be handled as group or not. Only use where necessary, use polymorphism where possible.
 138     @return whether the node is a feed group or not */
 139
 140     virtual bool isGroup() const = 0;
 141
 142     /** returns if the node represents an aggregation, i.e. containing
 143      * items from more than once source feed. Folders and virtual folders
 144      * are aggregations, feeds are not.
 145      */
 146     virtual bool isAggregation() const = 0;
 147
 148     /** exports node and child nodes to OPML (with akregator settings)
 149         @param parent the dom element the child node will be attached to
 150         @param document the opml document */
 151
 152     virtual QDomElement toOPML(QDomElement parent, QDomDocument document) const = 0;
 153
 154     /**
 155     @param doNotify notification on changes on/off flag
 156     @param notifyOccurredChanges notify changes occurred while turn off when set to true again */
 157
 158     virtual void setNotificationMode(bool doNotify);
 159
 160     /** returns the next node in the tree.
 161         Calling next() unless it returns 0 iterates through the tree in pre-order
 162      */
 163     virtual const TreeNode *next() const = 0;
 164     virtual TreeNode *next() = 0;
 165
 166     /** returns the ID of this node. IDs are managed by @ref FeedList objects and must be unique within the list. Some IDs have a special meaning:
 167     @c 0 is the default value and indicates that no ID was set
 168     @c 1 is reserved for the "All Feeds" root node */
 169     virtual uint id() const;
 170
 171     /** sets the ID */
 172     virtual void setId(uint id);
 173
 174     QPoint listViewScrollBarPositions() const;
 175     void setListViewScrollBarPositions(const QPoint &pos);
 176
 177     virtual KJob *createMarkAsReadJob() = 0;
 178
 179 public Q_SLOTS:
 180
 181     /** adds node to a fetch queue
 182         @param intervalFetchesOnly */
 183
 184     virtual void slotAddToFetchQueue(Akregator::FetchQueue *queue, bool intervalFetchesOnly = false) = 0;
 185
 186 Q_SIGNALS:
 187
 188     /** Emitted when this object is deleted. */
 189     void signalDestroyed(Akregator::TreeNode *);
 190
 191     /** Notification mechanism: emitted, when the node was modified and notification is enabled. A node change is renamed title, icon, unread count. Added, updated or removed articles are not notified via this signal */
 192     void signalChanged(Akregator::TreeNode *);
 193
 194     /** emitted when new articles were added to this node or any node in the subtree (for folders). Note that this has nothing to do with fetching, the article might have been moved from somewhere else in the tree into this subtree, e.g. by moving the feed the article is in.
 195         @param TreeNode* the node articles were added to
 196         @param QStringList the guids of the articles added
 197     */
 198     void signalArticlesAdded(Akregator::TreeNode *, const QVector<Akregator::Article> &guids);
 199
 200     /** emitted when articles were updated */
 201     void signalArticlesUpdated(Akregator::TreeNode *, const QVector<Akregator::Article> &guids);
 202
 203     /** emitted when articles were removed from this subtree. Note that this has nothing to do with actual article deletion! The article might have moved somewhere else in the tree, e.g. if the user moved the feed */
 204     void signalArticlesRemoved(Akregator::TreeNode *, const QVector<Akregator::Article> &guids);
 205
 206 protected:
 207
 208     /** call this if you modified the actual node (title, unread count).
 209      Call this only when the _actual_ _node_ has changed, i.e. title, unread count. Don't use for article changes!
 210      Will do notification immediately or cache it, depending on @c m_doNotify. */
 211     virtual void nodeModified();
 212
 213     /** call this if the articles in the node were changed. Sends signalArticlesAdded/Updated/Removed signals
 214      Will do notification immediately or cache it, depending on @c m_doNotify. */
 215     virtual void articlesModified();
 216
 217     /** reimplement this in subclasses to do the actual notification
 218       called by articlesModified
 219     */
 220     virtual void doArticleNotification();
 221
 222     void emitSignalDestroyed();
 223
 224 private:
 225     /** Returns a sequence of the articles this node contains. For feed groups, this returns a concatenated list of all articles in the sub tree.
 226     @return sequence of articles */
 227
 228     virtual QVector<Article> articles() = 0;
 229
 230 private:
 231     class TreeNodePrivate;
 232     TreeNodePrivate *d;
 233 };
 234
 235 } // namespace Akregator
 236
 237 #endif // AKREGATOR_TREENODE_H