mailcommon/filterlog.h

   1 /*
   2     This file is part of KMail.
   3     Copyright (c) 2003 Andreas Gungl <a.gungl@gmx.de>
   4
   5     KMail is free software; you can redistribute it and/or modify it
   6     under the terms of the GNU General Public License, version 2, as
   7     published by the Free Software Foundation.
   8
   9     KMail is distributed in the hope that it will be useful, but
  10     WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  17
  18     In addition, as a special exception, the copyright holders give
  19     permission to link the code of this program with any edition of
  20     the Qt library by Trolltech AS, Norway (or with modified versions
  21     of Qt that use the same license as Qt), and distribute linked
  22     combinations including the two.  You must obey the GNU General
  23     Public License in all respects for all of the code used other than
  24     Qt.  If you modify this file, you may extend this exception to
  25     your version of the file, but you are not obligated to do so.  If
  26     you do not wish to do so, delete this exception statement from
  27     your version.
  28 */
  29 #ifndef MAILCOMMON_FILTERLOG_H
  30 #define MAILCOMMON_FILTERLOG_H
  31
  32 #include <QObject>
  33 #include <QStringList>
  34 #include <QTextDocument>
  35
  36 #include "mailcommon_export.h"
  37
  38 namespace MailCommon {
  39
  40 /**
  41  * @short KMail Filter Log Collector.
  42  *
  43  * The filter log helps to collect log information about the
  44  * filter process in KMail. It's implemented as singleton,
  45  * so it's easy to direct pieces of information to a unique
  46  * instance.
  47  * It's possible to activate / deactivate logging. All
  48  * collected log information can get thrown away, the
  49  * next added log entry is the first one until another
  50  * clearing.
  51  * A signal is emitted whenever a new logentry is added,
  52  * when the log was cleared or any log state was changed.
  53  *
  54  * @author Andreas Gungl <a.gungl@gmx.de>
  55  */
  56 class MAILCOMMON_EXPORT FilterLog : public QObject
  57 {
  58   Q_OBJECT
  59
  60   public:
  61     /**
  62      * Destroys the filter log.
  63      */
  64     virtual ~FilterLog();
  65
  66     /**
  67      * Returns the single global instance of the filter log.
  68      */
  69     static FilterLog* instance();
  70
  71     /**
  72      * Describes the type of content that will be logged.
  73      */
  74     enum ContentType
  75     {
  76       Meta               = 1, ///< Log all meta data.
  77       PatternDescription = 2, ///< Log all pattern description.
  78       RuleResult         = 4, ///< Log all rule matching results.
  79       PatternResult      = 8, ///< Log all pattern matching results.
  80       AppliedAction      = 16 ///< Log all applied actions.
  81     };
  82
  83     /**
  84      * Sets whether the filter log is currently @p active.
  85      */
  86     void setLogging( bool active );
  87
  88     /**
  89      * Returns whether the filter log is currently active.
  90      */
  91     bool isLogging() const;
  92
  93     /**
  94      * Sets the maximum @p size of the log in bytes.
  95      */
  96     void setMaxLogSize( long size = -1 );
  97
  98     /**
  99      * Returns the maximum size of the log in bytes.
 100      */
 101     long maxLogSize() const;
 102
 103     /**
 104      * Sets whether a given content @p type will be @p enabled for logging.
 105      */
 106     void setContentTypeEnabled( ContentType type, bool enabled );
 107
 108     /**
 109      * Returns whether the given content @p type is enabled for logging.
 110      */
 111     bool isContentTypeEnabled( ContentType type ) const;
 112
 113     /**
 114      * Adds the given log @p entry under the given content @p type to the log.
 115      */
 116     void add( const QString &entry, ContentType type );
 117
 118     /**
 119      * Adds a separator line to the log.
 120      */
 121     void addSeparator();
 122
 123     /**
 124      * Clears the log.
 125      */
 126     void clear();
 127
 128     /**
 129      * Returns the list of log entries.
 130      */
 131     QStringList logEntries() const;
 132
 133     /**
 134      * Saves the log to the file with the given @p fileName.
 135      *
 136      * @return @c true on success or @c false on failure.
 137      */
 138     bool saveToFile( const QString &fileName ) const;
 139
 140     /**
 141      * Returns an escaped version of the log which can be used
 142      * in a HTML document.
 143      */
 144     static QString recode( const QString &plain );
 145
 146     /**
 147      * Dumps the log to console. Used for debugging.
 148      */
 149     void dump();
 150
 151   Q_SIGNALS:
 152     /**
 153      * This signal is emitted whenever a new @p entry has been added to the log.
 154      */
 155     void logEntryAdded( const QString &entry );
 156
 157     /**
 158      * This signal is emitted whenever the log has shrinked.
 159      */
 160     void logShrinked();
 161
 162     /**
 163      * This signal is emitted whenever the activity of the filter log has been changed.
 164      */
 165     void logStateChanged();
 166
 167   private:
 168     //@cond PRIVATE
 169     FilterLog();
 170
 171     class Private;
 172     Private* const d;
 173     //@endcond
 174 };
 175
 176 }
 177
 178 #endif