KMail design principles
=======================

This file is intended to guide the reader's way through the KMail
codebase. It should esp. be handy for people not hacking full-time on
KMail as well as people that want to trace bugs in parts of KMail
which they don't know well.


TODO: reader, composer, messages, folder, accounts, ...

KERNEL
======

MESSAGES
========

COMPOSER
========

READER
======

FOLDER
======


ACCOUNT
=======


FILTER
=======

Contact Marc Mutz <mutz@kde.org> on questions...

Filters consist of a search pattern and a list of actions plus a few
flags to indicate when they are to be applied (kmfilter.h).
  They are managed in a QList<KMFilter>, called KMFilterMgr. This
filter magnager is responsible for loading and storing filters
(read/writeConfig) and for executing them (process). The unique
instance of the filter manager is held by the kernel
(KMKernel::filterMgr()).

The search pattern is a QList of search rules (kmsearchpattern.h) and a
boolean operator that defines their relation (and/or).

A search rule consists of a field-QString, a "function"-enum and a
"contents" or "value" QString. The first gives the header (or
pseudoheader) to match against, the second says how to match (equals,
consists, is less than,...) and the third holds the pattern to match
against.
  Currently, there are two types of search rules, whcih are mixed
together into a single class: String-valued and int-valued. The latter
is a hack to enable <size> and <age in days> pseudo-header matching.
  KMSearchRules should better be organized like KMFilterActions are.

A filter action (kmfilteraction.h) inherits from KMFilterAction or one
of it's convenience sub-classes. They have three sub-interfaces: (1)
argument handling, (2) processing and (3) parameter widget handling.
  Interface (1) consists of args{From,As}String(), name() and
isEmpty() and is used to read and write the arguments (if any) from/to
the config.
  Interface (2) is used by the filter manager to execute the action
(process() / ReturnCode).
  Interface (3) is used by the filter dialog to allow editing of
actions and consists of name(), label() and the
*ParamWidget*(). Complex parameter widgets are collected in
kmfawidget.{h,cpp}.

A typical call for applying filters is 

KMKernel::filterMgr()
foreach message {
  KMFilterMgr::process():
}