MailCommon::FilterAction Class

class MailCommon::FilterAction

Abstract base class for mail filter actions. More...

Header: #include <MailCommon/FilterAction>
CMake: find_package(KPim6MailCommon REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::MailCommon)
Inherits: QObject

Public Types

enum ReturnCode { ErrorNeedComplete, GoOn, ErrorButGoOn, CriticalError }

Public Functions

FilterAction(const QString &name, const QString &label, QObject *parent = nullptr)
virtual ~FilterAction() override
virtual void applyParamWidgetValue(QWidget *paramWidget)
virtual QString argsAsString() const = 0
virtual void argsFromString(const QString &argsStr) = 0
virtual bool argsFromStringInteractive(const QString &argsStr, const QString &filterName)
virtual void clearParamWidget(QWidget *paramWidget) const
virtual QWidget *createParamWidget(QWidget *parent) const
virtual QString displayString() const = 0
virtual bool folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder)
virtual bool isEmpty() const
QString label() const
QString name() const
virtual MailCommon::FilterAction::ReturnCode process(MailCommon::ItemContext &context, bool applyOnOutbound) const = 0
virtual MailCommon::SearchRule::RequiredPart requiredPart() const = 0
virtual void setParamWidgetValue(QWidget *paramWidget) const

Signals

Static Public Members

MailCommon::FilterAction *newAction()
void sendMDN(const Akonadi::Item &item, KMime::MDN::DispositionType d, const QList<KMime::MDN::DispositionModifier> &m = QList<KMime::MDN::DispositionModifier>())

Detailed Description

Abstract base class for mail filter actions. All it can do is hold a name (ie. type-string). There are several sub-classes that inherit form this and are capable of providing parameter handling (import/export as string, a widget to allow editing, etc.)

Author: Marc Mutz <mutz@kde.org>, based on work by Stefan Taferner <taferner@kde.org>.

See also MailFilter and FilterManager.

Member Type Documentation

enum FilterAction::ReturnCode

Describes the possible return codes of filter processing:

ConstantValueDescription
MailCommon::FilterAction::ErrorNeedComplete0x1Could not process because a complete message is needed.
MailCommon::FilterAction::GoOn0x2Go on with applying filter actions.
MailCommon::FilterAction::ErrorButGoOn0x4A non-critical error occurred (e.g. an invalid address in the 'forward' action), but processing should continue.
MailCommon::FilterAction::CriticalError0x8A critical error occurred during processing (e.g. "disk full").

Member Function Documentation

FilterAction::FilterAction(const QString &name, const QString &label, QObject *parent = nullptr)

Creates a new filter action.

The action is initialized with an identifier name and an i18n'd label, with the given parent.

[override virtual noexcept] FilterAction::~FilterAction()

Destroys the filter action.

[virtual] void FilterAction::applyParamWidgetValue(QWidget *paramWidget)

The filter action shall set it's parameter from the contents of paramWidget. It is allowed that the value is read by the action before this function is called.

[pure virtual] QString FilterAction::argsAsString() const

Return extra arguments as string. Must not contain newlines.

[pure virtual] void FilterAction::argsFromString(const QString &argsStr)

Read extra arguments from the given string argsStr.

[virtual] bool FilterAction::argsFromStringInteractive(const QString &argsStr, const QString &filterName)

Read extra arguments from the given string argsStr, for the filter named filterName. Returns true if we need to update config file.

[virtual] void FilterAction::clearParamWidget(QWidget *paramWidget) const

The filter action shall clear the contents of its parameter widget paramWidget.

[virtual] QWidget *FilterAction::createParamWidget(QWidget *parent) const

Creates a widget with the given parent for setting the filter action parameter. Also sets the value of the widget.

[pure virtual] QString FilterAction::displayString() const

Returns a translated string describing this filter for visualization purposes, e.g. in the filter log.

[signal] void FilterAction::filterActionModified()

Called to notify that the current FilterAction has had some value modification

[virtual] bool FilterAction::folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder)

Called from the filter when a folder is removed. Tests if the folder aFolder is used and changes to aNewFolder in this case. Returns true if a change was made.

[virtual] bool FilterAction::isEmpty() const

Returns true if this action is empty, i.e. not valid. But this is just a quick test. Eg., actions that have a mail address as parameter shouldn't try real address validation, but only check if the string representation is empty.

QString FilterAction::label() const

Returns i18n'd label, ie. the one which is presented in the filter dialog.

QString FilterAction::name() const

Returns identifier name, ie. the one under which it is known in the config.

[static] MailCommon::FilterAction *FilterAction::newAction()

Static function that creates a filter action of this type.

[pure virtual] MailCommon::FilterAction::ReturnCode FilterAction::process(MailCommon::ItemContext &context, bool applyOnOutbound) const

Execute action on given message (inside the item context). applyOnOutbound is true when the filter is applied on outgoing messages. Returns CriticalError if a critical error has occurred (eg. disk full), ErrorButGoOn if there was a non-critical error (e.g. invalid address in 'forward' action), ErrorNeedComplete if a complete message is required, GoOn if the message shall be processed by further filters and Ok otherwise.

[pure virtual] MailCommon::SearchRule::RequiredPart FilterAction::requiredPart() const

Returns the required part from the item that is needed for the action to operate. See MailCommon::SearchRule::RequiredPart

[static] void FilterAction::sendMDN(const Akonadi::Item &item, KMime::MDN::DispositionType d, const QList<KMime::MDN::DispositionModifier> &m = QList<KMime::MDN::DispositionModifier>())

Automates the sending of MDNs from filter actions: sends an MDN for item with the disposition type d and the disposition modifiers m.

[virtual] void FilterAction::setParamWidgetValue(QWidget *paramWidget) const

The filter action shall set the contents of paramWidget from it's parameter.