kmail Library API Documentation

KMSearchPattern Class Reference

This class is an abstraction of a search over messages. An abstraction of a search over messages. More...

#include <kmsearchpattern.h>

Inheritance diagram for KMSearchPattern:

QPtrList< KMSearchRule > List of all members.

Public Types

enum  Operator { OpAnd, OpOr }

Public Methods

 KMSearchPattern (const KConfig *config=0)
 ~KMSearchPattern ()
bool matches (const KMMessage *msg) const
bool matches (const DwString &str) const
bool matches (Q_UINT32 sernum) const
bool requiresBody () const
void purify ()
void readConfig (const KConfig *config)
void writeConfig (KConfig *config) const
QString name () const
void setName (const QString &newName)
KMSearchPattern::Operator op () const
void setOp (KMSearchPattern::Operator aOp)
QString asString () const
const KMSearchPattern & operator= (const KMSearchPattern &aPattern)

Detailed Description

This class is an abstraction of a search over messages. An abstraction of a search over messages.

It is intended to be used inside a KFilter (which adds KFilterAction's), as well as in KMSearch. It can read and write itself into a KConfig group and there is a constructor, mainly used by KMFilter to initialize from a preset KConfig-Group.

From a class hierarchy point of view, it is a QPtrList of KMSearchRule's that adds the boolean operators (see Operator) 'and' and 'or' that connect the rules logically, and has a name under which it could be stored in the config file.

As a QPtrList with autoDelete enabled, it assumes that it is the central repository for the rules it contains. So if you want to reuse a rule in another pattern, make a deep copy of that rule.

Author:
Marc Mutz <Marc@Mutz.com>

Definition at line 246 of file kmsearchpattern.h.


Member Enumeration Documentation

enum KMSearchPattern::Operator
 

Boolean operators that connect the return values of the individual rules.

A pattern with OpAnd will match iff all it's rules match, whereas a pattern with OpOr will match iff any of it's rules matches.

Definition at line 254 of file kmsearchpattern.h.

Referenced by op(), and setOp().


Constructor & Destructor Documentation

KMSearchPattern::KMSearchPattern const KConfig *    config = 0
 

Constructor that initializes from a given KConfig group, if given.

This feature is mainly (solely?) used in KMFilter, as we don't allow to store search patterns in the config (yet). If config is 0, provides a pattern with minimal, but sufficient initialization. Unmodified, such a pattern will fail to match any KMMessage. You can query for such an empty rule by using isEmpty, which is inherited from QPtrList.

Definition at line 513 of file kmsearchpattern.cpp.

References readConfig(), and QPtrList< KMSearchRule >::setAutoDelete().

KMSearchPattern::~KMSearchPattern  
 

Destructor.

Deletes all stored rules!

Definition at line 523 of file kmsearchpattern.cpp.


Member Function Documentation

bool KMSearchPattern::matches const KMMessage *    msg const
 

The central function of this class.

Tries to match the set of rules against a KMMessage. It's virtual to allow derived classes with added rules to reimplement it, yet reimplemented methods should and (&&) the result of this function with their own result or else most functionality is lacking, or has to be reimplemented, since the rules are private to this class.

Returns:
TRUE if the match was successful, FALSE otherwise.

Definition at line 527 of file kmsearchpattern.cpp.

References QPtrListIterator::current(), QPtrList< KMSearchRule >::isEmpty(), and QPtrListIterator::toFirst().

bool KMSearchPattern::requiresBody   const
 

Returns true if the pattern only depends the DwString that backs a message.

Definition at line 595 of file kmsearchpattern.cpp.

References QPtrListIterator::current(), and QPtrListIterator::toFirst().

void KMSearchPattern::purify  
 

Removes all empty rules from the list.

You should call this method whenever the user had had control of the rules outside of this class. (e.g. after editing it with KMSearchPatternEdit).

Definition at line 603 of file kmsearchpattern.cpp.

References QPtrListIterator::current(), QPtrList< KMSearchRule >::remove(), and QPtrListIterator::toLast().

void KMSearchPattern::readConfig const KConfig *    config
 

Reads a search pattern from a KConfig.

The group has to be preset. If it does not find a valid saerch pattern in the preset group, initializes the pattern as if it were constructed using the default constructor.

For backwards compatibility with previous versions of KMail, it checks for old-style filter rules (e.g. using OpIgnore) in config und converts them to the new format on writeConfig.

Derived classes reimplementing readConfig() should also call this method, or else the rules will not be loaded.

Definition at line 617 of file kmsearchpattern.cpp.

References QPtrList< KMSearchRule >::append(), KMSearchRule::createInstanceFromConfig(), and KMSearchRule::isEmpty().

Referenced by KMSearchPattern().

void KMSearchPattern::writeConfig KConfig *    config const
 

Writes itself into config.

The group has to be preset. Tries to delete old-style keys by overwriting them with QString::null.

Derived classes reimplementing writeConfig() should also call this method, or else the rules will not be stored.

Definition at line 683 of file kmsearchpattern.cpp.

References QPtrListIterator::current().

QString KMSearchPattern::name void    const [inline]
 

Get the name of the search pattern.

Definition at line 315 of file kmsearchpattern.h.

Referenced by operator=(), and KMFilterListBox::slotUpdateFilterName().

void KMSearchPattern::setName const QString   newName [inline]
 

Set the name of the search pattern.

KMFilter uses this to store it's own name, too.

Definition at line 318 of file kmsearchpattern.h.

Referenced by operator=(), and KMFilterListBox::slotUpdateFilterName().

KMSearchPattern::Operator KMSearchPattern::op   const [inline]
 

Get the filter operator.

Definition at line 321 of file kmsearchpattern.h.

References Operator.

Referenced by operator=(), and KMSearchPatternEdit::setSearchPattern().

void KMSearchPattern::setOp KMSearchPattern::Operator    aOp [inline]
 

Set the filter operator.

Definition at line 323 of file kmsearchpattern.h.

References Operator.

Referenced by operator=().

QString KMSearchPattern::asString   const
 

Returns the pattern as string.

For debugging.

Definition at line 704 of file kmsearchpattern.cpp.

References QPtrListIterator::current().

const KMSearchPattern & KMSearchPattern::operator= const KMSearchPattern &    aPattern
 

Overloaded assignment operator.

Makes a deep copy.

Definition at line 716 of file kmsearchpattern.cpp.

References QPtrList< KMSearchRule >::append(), QPtrList< KMSearchRule >::clear(), KMSearchRule::createInstance(), QPtrListIterator::current(), name(), op(), setName(), and setOp().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kmail Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 11:37:37 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003