Mailcommon

filteraction.h
1/*
2 * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <taferner@kde.org>
3 *
4 * SPDX-License-Identifier: GPL-2.0-or-later
5 *
6 */
7
8#pragma once
9
10#include "mailcommon_export.h"
11#include "searchpattern.h"
12
13#include "mailcommon/itemcontext.h"
14
15#include <Akonadi/Collection>
16#include <Akonadi/Item>
17
18#include <KMime/KMimeMessage>
19#include <KMime/MDN>
20
21#include <QObject>
22
23class QWidget;
24
25namespace MailCommon
26{
27/**
28 * @short Abstract base class for mail filter actions.
29 *
30 * Abstract base class for mail filter actions. All it can do is
31 * hold a name (ie. type-string). There are several sub-classes that
32 * inherit form this and are capable of providing parameter handling
33 * (import/export as string, a widget to allow editing, etc.)
34 *
35 * @author Marc Mutz <mutz@kde.org>, based on work by Stefan Taferner <taferner@kde.org>.
36 * @see Filter FilterMgr
37 */
38class MAILCOMMON_EXPORT FilterAction : public QObject
39{
40 Q_OBJECT
41public:
42 /**
43 * Describes the possible return codes of filter processing:
44 */
46 ErrorNeedComplete = 0x1, ///< Could not process because a complete message is needed.
47 GoOn = 0x2, ///< Go on with applying filter actions.
48 ErrorButGoOn = 0x4, ///< A non-critical error occurred
49 /// (e.g. an invalid address in the 'forward' action),
50 /// but processing should continue.
51 CriticalError = 0x8 ///< A critical error occurred during processing
52 /// (e.g. "disk full").
53 };
54
55 /**
56 * Creates a new filter action.
57 *
58 * The action is initialized with an identifier @p name and
59 * an i18n'd @p label.
60 */
61 FilterAction(const QString &name, const QString &label, QObject *parent = nullptr);
62
63 /**
64 * Destroys the filter action.
65 */
66 ~FilterAction() override;
67
68 /**
69 * Returns i18n'd label, ie. the one which is presented in
70 * the filter dialog.
71 */
72 [[nodiscard]] QString label() const;
73
74 /**
75 * Returns identifier name, ie. the one under which it is
76 * known in the config.
77 */
78 [[nodiscard]] QString name() const;
79
80 [[nodiscard]] virtual QStringList sieveRequires() const;
81
82 [[nodiscard]] virtual QString sieveCode() const;
83
84 /**
85 * Execute action on given message (inside the item context).
86 * Returns @p CriticalError if a
87 * critical error has occurred (eg. disk full), @p ErrorButGoOn if
88 * there was a non-critical error (e.g. invalid address in
89 * 'forward' action), @p ErrorNeedComplete if a complete message
90 * is required, @p GoOn if the message shall be processed by
91 * further filters and @p Ok otherwise.
92 */
93 [[nodiscard]] virtual ReturnCode process(ItemContext &context, bool applyOnOutbound) const = 0;
94
95 /**
96 * Returns the required part from the item that is needed for the action to
97 * operate. See @ref MailCommon::SearchRule::RequiredPart */
98 [[nodiscard]] virtual SearchRule::RequiredPart requiredPart() const = 0;
99 /**
100 * Determines whether this action is valid. But this is just a
101 * quick test. Eg., actions that have a mail address as parameter
102 * shouldn't try real address validation, but only check if the
103 * string representation is empty.
104 */
105 [[nodiscard]] virtual bool isEmpty() const;
106
107 [[nodiscard]] virtual QString informationAboutNotValidAction() const;
108
109 /**
110 * Creates a widget for setting the filter action parameter. Also
111 * sets the value of the widget.
112 */
113 [[nodiscard]] virtual QWidget *createParamWidget(QWidget *parent) const;
114
115 /**
116 * The filter action shall set it's parameter from the widget's
117 * contents. It is allowed that the value is read by the action
118 * before this function is called.
119 */
120 virtual void applyParamWidgetValue(QWidget *paramWidget);
121
122 /**
123 * The filter action shall set it's widget's contents from it's
124 * parameter.
125 */
126 virtual void setParamWidgetValue(QWidget *paramWidget) const;
127
128 /**
129 * The filter action shall clear it's parameter widget's
130 * contents.
131 */
132 virtual void clearParamWidget(QWidget *paramWidget) const;
133
134 /**
135 * Read extra arguments from given string.
136 */
137 virtual void argsFromString(const QString &argsStr) = 0;
138
139 /**
140 * Read extra arguments from given string.
141 * Return true if we need to update config file
142 */
143 [[nodiscard]] virtual bool argsFromStringInteractive(const QString &argsStr, const QString &filterName);
144
145 [[nodiscard]] virtual QString argsAsStringReal() const;
146
147 /**
148 * Return extra arguments as string. Must not contain newlines.
149 */
150 [[nodiscard]] virtual QString argsAsString() const = 0;
151
152 /**
153 * Returns a translated string describing this filter for visualization
154 * purposes, e.g. in the filter log.
155 */
156 [[nodiscard]] virtual QString displayString() const = 0;
157
158 /**
159 * Called from the filter when a folder is removed. Tests if the
160 * folder @p aFolder is used and changes to @p aNewFolder in this
161 * case. Returns true if a change was made.
162 */
163 [[nodiscard]] virtual bool folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder);
164
165 /**
166 * Static function that creates a filter action of this type.
167 */
168 static FilterAction *newAction();
169
170 /**
171 * Automates the sending of MDNs from filter actions.
172 */
173 static void sendMDN(const Akonadi::Item &item,
174 KMime::MDN::DispositionType d,
176
177Q_SIGNALS:
178 /**
179 * Called to notify that the current FilterAction has had some
180 * value modification
181 */
183
184private:
185 const QString mName;
186 const QString mLabel;
187};
188}
Abstract base class for mail filter actions.
virtual void argsFromString(const QString &argsStr)=0
Read extra arguments from given string.
~FilterAction() override
Destroys the filter action.
virtual SearchRule::RequiredPart requiredPart() const =0
Returns the required part from the item that is needed for the action to operate.
virtual QString displayString() const =0
Returns a translated string describing this filter for visualization purposes, e.g.
virtual QString argsAsString() const =0
Return extra arguments as string.
virtual ReturnCode process(ItemContext &context, bool applyOnOutbound) const =0
Execute action on given message (inside the item context).
ReturnCode
Describes the possible return codes of filter processing:
void filterActionModified()
Called to notify that the current FilterAction has had some value modification.
A helper class for the filtering process.
Definition itemcontext.h:27
RequiredPart
Possible required parts.
Definition searchrule.h:68
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:51:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.