knode/kscoring.h

   1 /*
   2   kscoring.h
   3
   4   Copyright (c) 2001 Mathias Waack <mathias@atoll-net.de>
   5   Copyright (C) 2005 by Volker Krause <vkrause@kde.org>
   6
   7   Author: Mathias Waack <mathias@atoll-net.de>
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13   You should have received a copy of the GNU General Public License
  14   along with this program; if not, write to the Free Software Foundation,
  15   Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, US
  16 */
  17
  18 #ifndef KDEPIM_KSCORING_H
  19 #define KDEPIM_KSCORING_H
  20
  21 #include "knode_export.h"
  22
  23 #include <KDialog>
  24
  25 #include <QColor>
  26 #include <QMap>
  27 #include <QObject>
  28 #include <QRegExp>
  29 #include <QString>
  30 #include <QStringList>
  31 #include <QTextStream>
  32 #include <Q3Dict>
  33 #include <Q3PtrList>
  34 #include <Q3PtrStack>
  35
  36 #include <unistd.h>
  37
  38 class QDomNode;
  39 class QDomDocument;
  40 class QDomElement;
  41 class QLabel;
  42
  43 namespace KPIM {
  44
  45 /**
  46   The following classes ScorableArticle, ScorableGroup define
  47   the interface for the scoring. Any application using this mechanism should
  48   create its own subclasses of this classes. The scoring itself will be handled
  49   by the ScoringManager class.
  50  */
  51
  52 //----------------------------------------------------------------------------
  53 class KNODE_EXPORT ScorableGroup
  54 {
  55 public:
  56   virtual ~ScorableGroup();
  57 };
  58
  59 class KNODE_EXPORT ScorableArticle
  60 {
  61   public:
  62     virtual ~ScorableArticle();
  63
  64     virtual void addScore( short ) {}
  65     virtual void displayMessage( const QString & );
  66     virtual void changeColor( const QColor & ) {}
  67     virtual void markAsRead() {}
  68     virtual QString from() const = 0;
  69     virtual QString subject() const = 0;
  70     virtual QString getHeaderByType( const QString & ) const = 0;
  71 };
  72
  73 //----------------------------------------------------------------------------
  74 /**
  75   Base class for other Action classes.
  76  */
  77 class KNODE_EXPORT ActionBase {
  78   public:
  79     ActionBase();
  80     virtual ~ActionBase();
  81     virtual QString toString() const = 0;
  82     virtual void apply( ScorableArticle & ) const = 0;
  83     virtual ActionBase *clone() const = 0;
  84     virtual int getType() const = 0;
  85     virtual QString getValueString() const { return QString(); }
  86     virtual void setValue( const QString & ) {}
  87     static ActionBase *factory( int type, const QString &value );
  88     static QStringList userNames();
  89     static QString userName( int type );
  90     static int getTypeForName( const QString &name );
  91     static int getTypeForUserName( const QString &name );
  92     QString userName() { return userName( getType() ); }
  93     enum ActionTypes {
  94       SETSCORE,
  95       NOTIFY,
  96       COLOR,
  97       MARKASREAD
  98     };
  99 };
 100
 101 class KNODE_EXPORT ActionColor : public ActionBase {
 102   public:
 103     ActionColor( const QColor & );
 104     ActionColor( const QString & );
 105     ActionColor( const ActionColor & );
 106     virtual ~ActionColor();
 107     virtual QString toString() const;
 108     virtual int getType() const { return COLOR; }
 109     virtual QString getValueString() const { return color.name(); }
 110     virtual void setValue( const QString &s ) { color.setNamedColor(s); }
 111     void setValue( const QColor &c ) { color = c; }
 112     QColor value() const { return color; }
 113     virtual void apply( ScorableArticle & ) const;
 114     virtual ActionColor *clone() const;
 115
 116   private:
 117     QColor color;
 118 };
 119
 120 class KNODE_EXPORT ActionSetScore : public ActionBase {
 121   public:
 122     ActionSetScore( short );
 123     ActionSetScore( const ActionSetScore & );
 124     ActionSetScore( const QString & );
 125     virtual ~ActionSetScore();
 126     virtual QString toString() const;
 127     virtual int getType() const { return SETSCORE; }
 128     virtual QString getValueString() const { return QString::number(val); }
 129     virtual void setValue( const QString &s ) { val = s.toShort(); }
 130     void setValue( short v ) { val = v; }
 131     short value() const { return val; }
 132     virtual void apply( ScorableArticle & ) const;
 133     virtual ActionSetScore *clone() const;
 134
 135   private:
 136     short val;
 137 };
 138
 139 class KNODE_EXPORT ActionNotify : public ActionBase {
 140   public:
 141     ActionNotify( const QString & );
 142     ActionNotify( const ActionNotify & );
 143     virtual ~ActionNotify() {}
 144     virtual QString toString() const;
 145     virtual int getType() const { return NOTIFY; }
 146     virtual QString getValueString() const { return note; }
 147     virtual void setValue( const QString &s ) { note = s; }
 148     virtual void apply( ScorableArticle & ) const;
 149     virtual ActionNotify *clone() const;
 150
 151   private:
 152     QString note;
 153 };
 154
 155 class KNODE_EXPORT ActionMarkAsRead : public ActionBase {
 156     public:
 157     ActionMarkAsRead();
 158     ActionMarkAsRead( const ActionMarkAsRead & );
 159     virtual ~ActionMarkAsRead() {}
 160     virtual QString toString() const;
 161     virtual int getType() const { return MARKASREAD; }
 162     virtual void apply( ScorableArticle &article ) const;
 163     virtual ActionMarkAsRead *clone() const;
 164 };
 165
 166 class KNODE_EXPORT NotifyCollection
 167 {
 168   public:
 169     NotifyCollection();
 170     ~NotifyCollection();
 171     void addNote( const ScorableArticle &, const QString & );
 172     QString collection() const;
 173     void displayCollection( QWidget *p=0 ) const;
 174   private:
 175     struct article_info {
 176       QString from;
 177       QString subject;
 178     };
 179     typedef QList<article_info> article_list;
 180     typedef Q3Dict<article_list> note_list;
 181     note_list notifyList;
 182 };
 183
 184 //----------------------------------------------------------------------------
 185 class KNODE_EXPORT KScoringExpression
 186 {
 187   friend class KScoringRule;
 188   public:
 189     enum Condition {
 190       CONTAINS,
 191       MATCH,
 192       EQUALS,
 193       SMALLER,
 194       GREATER,
 195       MATCHCS
 196     };
 197
 198     KScoringExpression( const QString &, const QString &, const QString &, const QString & );
 199     ~KScoringExpression();
 200
 201     bool match( ScorableArticle &a ) const ;
 202     QString getTypeString() const;
 203     static QString getTypeString( int );
 204     int getType() const;
 205     QString toString() const;
 206     void write( QTextStream & ) const;
 207
 208     bool isNeg() const { return neg; }
 209     Condition getCondition() const { return cond; }
 210     QString getExpression() const { return expr_str; }
 211     QString getHeader() const { return header; }
 212     static QStringList conditionNames();
 213     static QStringList headerNames();
 214     static int getConditionForName( const QString & );
 215     static QString getNameForCondition( int );
 216
 217   private:
 218     bool neg;
 219     QString header;
 220     Condition cond;
 221     QRegExp expr;
 222     QString expr_str;
 223     int expr_int;
 224 };
 225
 226 //----------------------------------------------------------------------------
 227 class KNODE_EXPORT KScoringRule
 228 {
 229   friend class KScoringManager;
 230   public:
 231     KScoringRule( const QString &name );
 232     KScoringRule( const KScoringRule &r );
 233     ~KScoringRule();
 234
 235     typedef Q3PtrList<KScoringExpression> ScoreExprList;
 236     typedef Q3PtrList<ActionBase> ActionList;
 237     typedef QStringList GroupList;
 238     enum LinkMode {
 239       AND,
 240       OR
 241     };
 242
 243     QString getName() const { return name; }
 244     QStringList getGroups() const { return groups; }
 245     void setGroups( const QStringList &l ) { groups = l; }
 246     LinkMode getLinkMode() const { return link; }
 247     QString getLinkModeName() const;
 248     QString getExpireDateString() const;
 249     QDate getExpireDate() const { return expires; }
 250     void setExpireDate( const QDate &d ) { expires = d; }
 251     bool isExpired() const;
 252     ScoreExprList getExpressions() const { return expressions; }
 253     ActionList getActions() const { return actions; }
 254     void cleanExpressions();
 255     void cleanActions();
 256
 257     bool matchGroup( const QString &group ) const ;
 258     void applyRule( ScorableArticle &a ) const;
 259     void applyRule( ScorableArticle &a, const QString &group ) const;
 260     void applyAction( ScorableArticle &a ) const;
 261
 262     void setLinkMode( const QString &link );
 263     void setLinkMode( LinkMode m ) { link = m; }
 264     void setExpire( const QString &exp );
 265     void addExpression( KScoringExpression * );
 266     void addGroup( const QString &group ) { groups.append(group); }
 267     void addAction( int, const QString & );
 268     void addAction(ActionBase*);
 269
 270     void updateXML( QDomElement &e, QDomDocument &d );
 271     QString toString() const;
 272
 273     // writes the rule in XML format into the textstream
 274     void write( QTextStream & ) const;
 275
 276   protected:
 277     //! assert that the name is unique
 278     void setName( const QString &n ) { name = n; }
 279
 280   private:
 281     QString name;
 282     GroupList groups;
 283     //ServerList servers;
 284     LinkMode link;
 285     ScoreExprList expressions;
 286     ActionList actions;
 287     QDate expires;
 288 };
 289
 290 /** this helper class implements a stack for lists of lists of rules.
 291     With the help of this class it is very easy for the KScoringManager
 292     to temporary drop lists of rules and restore them afterwards
 293 */
 294 class KNODE_EXPORT RuleStack
 295 {
 296   public:
 297     RuleStack();
 298     ~RuleStack();
 299     //! puts the list on the stack, doesn't change the list
 300     void push( Q3PtrList<KScoringRule>& );
 301     //! clears the argument list and copy the content of the TOS into it
 302     //! after that the TOS gets dropped
 303     void pop( Q3PtrList<KScoringRule>& );
 304     //! like pop but without dropping the TOS
 305     void top( Q3PtrList<KScoringRule>& );
 306     //! drops the TOS
 307     void drop();
 308
 309   private:
 310     Q3PtrStack< Q3PtrList<KScoringRule> > stack;
 311 };
 312
 313 //----------------------------------------------------------------------------
 314 // Manages the score rules.
 315 class KNODE_EXPORT KScoringManager : public QObject
 316 {
 317   Q_OBJECT
 318   public:
 319     // this is the container for all rules
 320     typedef Q3PtrList<KScoringRule> ScoringRuleList;
 321
 322     KScoringManager( const QString &appName = QString() );
 323     virtual ~KScoringManager();
 324
 325     // returns a list of all available groups, must be overridden
 326     virtual QStringList getGroups() const = 0;
 327
 328     //! returns a list of common (or available) headers
 329     //! defaults to returning { Subject, From, Message-ID, Date }
 330     virtual QStringList getDefaultHeaders() const;
 331
 332     // setting current server and group and calling applyRules(ScorableArticle&)
 333     void applyRules( ScorableArticle &article, const QString &group );
 334     // assuming a properly set group
 335     void applyRules( ScorableArticle & );
 336     // same as above
 337     void applyRules( ScorableGroup *group );
 338
 339     // pushes the current rule list onto a stack
 340     void pushRuleList();
 341     // restores the current rule list from list stored on a stack
 342     // by a previous call to pushRuleList (this implicitly deletes the
 343     // current rule list)
 344     void popRuleList();
 345     // removes the TOS from the stack of rule lists
 346     void removeTOS();
 347
 348     KScoringRule *addRule( KScoringRule * );
 349     KScoringRule *addRule( const ScorableArticle &a, const QString &group, short score=0 );
 350     KScoringRule *addRule();
 351     void cancelNewRule( KScoringRule * );
 352     void deleteRule( KScoringRule * );
 353     void editRule( KScoringRule *e, QWidget *w=0 );
 354     KScoringRule *copyRule( KScoringRule * );
 355     void moveRuleAbove( KScoringRule *above, KScoringRule *below );
 356     void moveRuleBelow( KScoringRule *below, KScoringRule *above );
 357     void setGroup( const QString &g );
 358     // has to be called after setGroup() or initCache()
 359     bool hasRulesForCurrentGroup();
 360     QString findUniqueName() const;
 361
 362     /** called from an editor whenever it finishes editing the rule base,
 363         causes the finishedEditing signal to be emitted */
 364     void editorReady();
 365
 366     ScoringRuleList getAllRules() const { return allRules; }
 367     KScoringRule *findRule( const QString & );
 368     QStringList getRuleNames();
 369     void setRuleName( KScoringRule *, const QString & );
 370     int getRuleCount() const { return allRules.count(); }
 371     QString toString() const;
 372
 373     bool setCacheValid( bool v );
 374     bool isCacheValid() { return cacheValid; }
 375     void initCache( const QString &group );
 376
 377     void load();
 378     void save();
 379
 380     //--------------- Properties
 381     virtual bool canScores() const { return true; }
 382     virtual bool canNotes() const { return true; }
 383     virtual bool canColors() const { return false; }
 384     virtual bool canMarkAsRead() const { return false; }
 385     virtual bool hasFeature( int );
 386
 387   Q_SIGNALS:
 388     void changedRules();
 389     void changedRuleName( const QString &oldName, const QString &newName );
 390     void finishedEditing();
 391
 392   private:
 393     void addRuleInternal( KScoringRule *e );
 394     void expireRules();
 395
 396     QDomDocument createXMLfromInternal();
 397     void createInternalFromXML(QDomNode);
 398
 399     // list of all Rules
 400     ScoringRuleList allRules;
 401
 402     // the stack for temporary storing rule lists
 403     RuleStack stack;
 404
 405     // for the cache
 406     bool cacheValid;
 407     // current rule set, ie the cache
 408     ScoringRuleList ruleList;
 409     //QString server;
 410     QString group;
 411
 412     //ScorableServer* _s;
 413
 414     // filename of the scorefile
 415     QString mFilename;
 416 };
 417
 418 //----------------------------------------------------------------------------
 419 class KNODE_EXPORT NotifyDialog : public KDialog
 420 {
 421   Q_OBJECT
 422   public:
 423     static void display( ScorableArticle &, const QString & );
 424
 425   protected Q_SLOTS:
 426     void slotShowAgainToggled( bool );
 427
 428   private:
 429     NotifyDialog( QWidget *p=0 );
 430     static NotifyDialog *me;
 431
 432     QLabel *note;
 433     QString msg;
 434     typedef QMap<QString,bool> NotesMap;
 435     static NotesMap dict;
 436 };
 437
 438 }
 439
 440 #endif