libkdepim/kscoring.h

   1 /*
   2   kscoring.h
   3
   4   Copyright (c) 2001 Mathias Waack <mathias@atoll-net.de>
   5   Copyright (C) 2005 by Volker Krause <volker.krause@rwth-aachen.de>
   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 "kdepim_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 KDEPIM_EXPORT ScorableGroup
  54 {
  55 public:
  56   virtual ~ScorableGroup();
  57 };
  58
  59 class KDEPIM_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 KDEPIM_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 KDEPIM_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 KDEPIM_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 KDEPIM_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 KDEPIM_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 KDEPIM_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 KDEPIM_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     const char *c_header;
 221     Condition cond;
 222     QRegExp expr;
 223     QString expr_str;
 224     int expr_int;
 225 };
 226
 227 //----------------------------------------------------------------------------
 228 class KDEPIM_EXPORT KScoringRule
 229 {
 230   friend class KScoringManager;
 231   public:
 232     KScoringRule( const QString &name );
 233     KScoringRule( const KScoringRule &r );
 234     ~KScoringRule();
 235
 236     typedef Q3PtrList<KScoringExpression> ScoreExprList;
 237     typedef Q3PtrList<ActionBase> ActionList;
 238     typedef QStringList GroupList;
 239     enum LinkMode {
 240       AND,
 241       OR
 242     };
 243
 244     QString getName() const { return name; }
 245     QStringList getGroups() const { return groups; }
 246     void setGroups( const QStringList &l ) { groups = l; }
 247     LinkMode getLinkMode() const { return link; }
 248     QString getLinkModeName() const;
 249     QString getExpireDateString() const;
 250     QDate getExpireDate() const { return expires; }
 251     void setExpireDate( const QDate &d ) { expires = d; }
 252     bool isExpired() const;
 253     ScoreExprList getExpressions() const { return expressions; }
 254     ActionList getActions() const { return actions; }
 255     void cleanExpressions();
 256     void cleanActions();
 257
 258     bool matchGroup( const QString &group ) const ;
 259     void applyRule( ScorableArticle &a ) const;
 260     void applyRule( ScorableArticle &a, const QString &group ) const;
 261     void applyAction( ScorableArticle &a ) const;
 262
 263     void setLinkMode( const QString &link );
 264     void setLinkMode( LinkMode m ) { link = m; }
 265     void setExpire( const QString &exp );
 266     void addExpression( KScoringExpression * );
 267     void addGroup( const QString &group ) { groups.append(group); }
 268     void addAction( int, const QString & );
 269     void addAction(ActionBase*);
 270
 271     void updateXML( QDomElement &e, QDomDocument &d );
 272     QString toString() const;
 273
 274     // writes the rule in XML format into the textstream
 275     void write( QTextStream & ) const;
 276
 277   protected:
 278     //! assert that the name is unique
 279     void setName( const QString &n ) { name = n; }
 280
 281   private:
 282     QString name;
 283     GroupList groups;
 284     //ServerList servers;
 285     LinkMode link;
 286     ScoreExprList expressions;
 287     ActionList actions;
 288     QDate expires;
 289 };
 290
 291 /** this helper class implements a stack for lists of lists of rules.
 292     With the help of this class its very easy for the KScoringManager
 293     to temporary drop lists of rules and restore them afterwards
 294 */
 295 class KDEPIM_EXPORT RuleStack
 296 {
 297   public:
 298     RuleStack();
 299     ~RuleStack();
 300     //! puts the list on the stack, doesn't change the list
 301     void push( Q3PtrList<KScoringRule>& );
 302     //! clears the argument list and copy the content of the TOS into it
 303     //! after that the TOS gets dropped
 304     void pop( Q3PtrList<KScoringRule>& );
 305     //! like pop but without dropping the TOS
 306     void top( Q3PtrList<KScoringRule>& );
 307     //! drops the TOS
 308     void drop();
 309
 310   private:
 311     Q3PtrStack< Q3PtrList<KScoringRule> > stack;
 312 };
 313
 314 //----------------------------------------------------------------------------
 315 // Manages the score rules.
 316 class KDEPIM_EXPORT KScoringManager : public QObject
 317 {
 318   Q_OBJECT
 319   public:
 320     // this is the container for all rules
 321     typedef Q3PtrList<KScoringRule> ScoringRuleList;
 322
 323     KScoringManager( const QString &appName = QString() );
 324     virtual ~KScoringManager();
 325
 326     // returns a list of all available groups, must be overridden
 327     virtual QStringList getGroups() const = 0;
 328
 329     //! returns a list of common (or available) headers
 330     //! defaults to returning { Subject, From, Message-ID, Date }
 331     virtual QStringList getDefaultHeaders() const;
 332
 333     // setting current server and group and calling applyRules(ScorableArticle&)
 334     void applyRules( ScorableArticle &article, const QString &group );
 335     // assuming a properly set group
 336     void applyRules( ScorableArticle & );
 337     // same as above
 338     void applyRules( ScorableGroup *group );
 339
 340     // pushes the current rule list onto a stack
 341     void pushRuleList();
 342     // restores the current rule list from list stored on a stack
 343     // by a previous call to pushRuleList (this implicitly deletes the
 344     // current rule list)
 345     void popRuleList();
 346     // removes the TOS from the stack of rule lists
 347     void removeTOS();
 348
 349     KScoringRule *addRule( KScoringRule * );
 350     KScoringRule *addRule( const ScorableArticle &a, const QString &group, short score=0 );
 351     KScoringRule *addRule();
 352     void cancelNewRule( KScoringRule * );
 353     void deleteRule( KScoringRule * );
 354     void editRule( KScoringRule *e, QWidget *w=0 );
 355     KScoringRule *copyRule( KScoringRule * );
 356     void moveRuleAbove( KScoringRule *above, KScoringRule *below );
 357     void moveRuleBelow( KScoringRule *below, KScoringRule *above );
 358     void setGroup( const QString &g );
 359     // has to be called after setGroup() or initCache()
 360     bool hasRulesForCurrentGroup();
 361     QString findUniqueName() const;
 362
 363     /** called from an editor whenever it finishes editing the rule base,
 364         causes the finishedEditing signal to be emitted */
 365     void editorReady();
 366
 367     ScoringRuleList getAllRules() const { return allRules; }
 368     KScoringRule *findRule( const QString & );
 369     QStringList getRuleNames();
 370     void setRuleName( KScoringRule *, const QString & );
 371     int getRuleCount() const { return allRules.count(); }
 372     QString toString() const;
 373
 374     bool setCacheValid( bool v );
 375     bool isCacheValid() { return cacheValid; }
 376     void initCache( const QString &group );
 377
 378     void load();
 379     void save();
 380
 381     //--------------- Properties
 382     virtual bool canScores() const { return true; }
 383     virtual bool canNotes() const { return true; }
 384     virtual bool canColors() const { return false; }
 385     virtual bool canMarkAsRead() const { return false; }
 386     virtual bool hasFeature( int );
 387
 388   Q_SIGNALS:
 389     void changedRules();
 390     void changedRuleName( const QString &oldName, const QString &newName );
 391     void finishedEditing();
 392
 393   private:
 394     void addRuleInternal( KScoringRule *e );
 395     void expireRules();
 396
 397     QDomDocument createXMLfromInternal();
 398     void createInternalFromXML(QDomNode);
 399
 400     // list of all Rules
 401     ScoringRuleList allRules;
 402
 403     // the stack for temporary storing rule lists
 404     RuleStack stack;
 405
 406     // for the cache
 407     bool cacheValid;
 408     // current rule set, ie the cache
 409     ScoringRuleList ruleList;
 410     //QString server;
 411     QString group;
 412
 413     //ScorableServer* _s;
 414
 415     // filename of the scorefile
 416     QString mFilename;
 417 };
 418
 419 //----------------------------------------------------------------------------
 420 class KDEPIM_EXPORT NotifyDialog : public KDialog
 421 {
 422   Q_OBJECT
 423   public:
 424     static void display( ScorableArticle &, const QString & );
 425
 426   protected Q_SLOTS:
 427     void slotShowAgainToggled( bool );
 428
 429   private:
 430     NotifyDialog( QWidget *p=0 );
 431     static NotifyDialog *me;
 432
 433     QLabel *note;
 434     QString msg;
 435     typedef QMap<QString,bool> NotesMap;
 436     static NotesMap dict;
 437 };
 438
 439 }
 440
 441 #endif