MailCommon::MailFilter Class

class MailCommon::MailFilter

The MailFilter class. More...

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

Public Types

enum AccountType { All, ButImap, Checked }
enum ReturnCode { NoResult, GoOn, CriticalError }

Public Functions

MailFilter()
MailFilter(const KConfigGroup &aConfig, bool interactive, bool &needUpdate)
MailFilter(const MailCommon::MailFilter &other)
~MailFilter()
QList<MailCommon::FilterAction *> *actions()
const QList<MailCommon::FilterAction *> *actions() const
void agentRemoved(const QString &identifier)
MailCommon::MailFilter::AccountType applicability() const
bool applyBeforeOutbound() const
bool applyOnAccount(const QString &id) const
bool applyOnAllFoldersInbound() const
bool applyOnExplicit() const
bool applyOnInbound() const
bool applyOnOutbound() const
const QString asString() const
void clearApplyOnAccount()
bool configureShortcut() const
bool configureToolbar() const
MailCommon::MailFilter::ReturnCode execActions(MailCommon::ItemContext &context, bool &stopIt, bool applyOnOutbound) const
void folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder)
void generateRandomIdentifier()
void generateSieveScript(QStringList &requiresModules, QString &code)
QString icon() const
QString identifier() const
bool isAutoNaming() const
bool isEmpty() const
bool isEnabled() const
QString name() const
MailCommon::SearchPattern *pattern()
const MailCommon::SearchPattern *pattern() const
QString purify(bool removeAction = true)
bool readConfig(const KConfigGroup &config, bool interactive = false)
MailCommon::SearchRule::RequiredPart requiredPart(const QString &id) const
void setApplicability(MailCommon::MailFilter::AccountType apply = All)
void setApplyBeforeOutbound(bool apply)
void setApplyOnAccount(const QString &id, bool apply = true)
void setApplyOnAllFoldersInbound(bool apply)
void setApplyOnExplicit(bool apply)
void setApplyOnInbound(bool apply)
void setApplyOnOutbound(bool apply)
void setAutoNaming(bool useAutomaticNames)
void setConfigureShortcut(bool aShort)
void setConfigureToolbar(bool aTool)
void setEnabled(bool)
void setIcon(const QString &icon)
void setShortcut(const QKeySequence &shortcut)
void setToolbarName(const QString &toolbarName)
const QKeySequence &shortcut() const
QString toolbarName() const
void writeConfig(KConfigGroup &config, bool exportFilter) const

Static Public Members

Detailed Description

Member Type Documentation

enum MailFilter::AccountType

Account type codes used by setApplicability.

ConstantValueDescription
MailCommon::MailFilter::All0Apply to all accounts
MailCommon::MailFilter::ButImap1Apply to all but IMAP accounts
MailCommon::MailFilter::Checked2Apply to all accounts specified by setApplyOnAccount

enum MailFilter::ReturnCode

Result codes returned by process.

ConstantValueDescription
MailCommon::MailFilter::NoResult0For internal use only!
MailCommon::MailFilter::GoOn1Everything OK. You are still the owner of the message and you should continue applying filter actions to this message.
MailCommon::MailFilter::CriticalError2A critical error occurred (e.g. "disk full").

Member Function Documentation

MailFilter::MailFilter()

Constructor that initializes basic settings.

[explicit] MailFilter::MailFilter(const KConfigGroup &aConfig, bool interactive, bool &needUpdate)

Constructor that initializes from the given config group aConfig. Filters are stored one by one in config groups, i.e. one filter, one group. If interactive is true, the user may be asked to fix the filter. needUpdate is set to true if the configuration needs to be written back.

MailFilter::MailFilter(const MailCommon::MailFilter &other)

Copy constructor. Constructs a deep copy of other.

[noexcept] MailFilter::~MailFilter()

Cleanup.

QList<MailCommon::FilterAction *> *MailFilter::actions()

Provides a reference to the internal action list. If your used the setAction() and action() functions before, please convert to using myFilter->actions()->at() and friends now.

const QList<MailCommon::FilterAction *> *MailFilter::actions() const

Provides a reference to the internal action list. Const version.

void MailFilter::agentRemoved(const QString &identifier)

Called when the agent identifier is removed: the filter no longer applies to this account.

MailCommon::MailFilter::AccountType MailFilter::applicability() const

Returns true if this filter should be applied on inbound messages for all accounts, or false if this filter is to be applied on a specified set of accounts only. Only applicable to filters that are applied on inbound messages.

See also setApplicability.

bool MailFilter::applyBeforeOutbound() const

Returns TRUE if this filter should be applied on outbound messages before they are sent, FALSE otherwise.

See also setApplyBeforeOutbound(), setApplyOnOutbound, applyOnInbound, and setApplyOnInbound.

bool MailFilter::applyOnAccount(const QString &id) const

Returns true if this filter should be applied on inbound messages from the account with id (id), false otherwise.

See also setApplyOnAccount() and setApplicability.

bool MailFilter::applyOnAllFoldersInbound() const

Returns whether the filter should be applied on inbound emails in all folders, not just Inbox.

See also setApplyOnAllFoldersInbound().

bool MailFilter::applyOnExplicit() const

Returns true if this filter should be applied on explicit (CTRL-J) filtering, false otherwise.

See also setApplyOnExplicit(), setApplyOnOutbound, applyOnOutbound, and setApplyOnInbound.

bool MailFilter::applyOnInbound() const

Returns true if this filter should be applied on inbound messages, false otherwise.

See also setApplyOnOutbound, applyOnOutbound, and setApplyOnInbound.

bool MailFilter::applyOnOutbound() const

Returns true if this filter should be applied on outbound messages, false otherwise.

See also setApplyOnOutbound, applyOnInbound, and setApplyOnInbound.

const QString MailFilter::asString() const

Returns the filter in a human-readable form. useful for debugging but not much else. Don't use, as it may well go away in the future...

void MailFilter::clearApplyOnAccount()

Clears the list of accounts this filter applies to.

bool MailFilter::configureShortcut() const

Returns true if this filter should be plugged into the filter menu, false otherwise.

See also setConfigureShortcut.

bool MailFilter::configureToolbar() const

Returns true if this filter should be plugged into the toolbar, false otherwise.

See also setConfigureToolbar.

MailCommon::MailFilter::ReturnCode MailFilter::execActions(MailCommon::ItemContext &context, bool &stopIt, bool applyOnOutbound) const

Execute the filter action(s) on the given message. Returns:

  • 2 if a critical error occurred,
  • 1 if the caller is still the owner of the message,
  • 0 if processed successfully.

context The context that contains the item to which the actions should be applied. stopIt Contains true if the caller may apply other filters and false if he shall stop the filtering of this message. applyOnOutbound Defines whether to apply the rules on the outbound.

[static] int MailFilter::filterActionsMaximumSize()

Returns the maximum number of actions of a filter.

void MailFilter::folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder)

Called from the filter manager when a folder is moved. Tests if the folder aFolder is used in any action. Changes it to aNewFolder folder in this case.

void MailFilter::generateRandomIdentifier()

Generates a new random identifier for this filter.

void MailFilter::generateSieveScript(QStringList &requiresModules, QString &code)

Generates the Sieve script code of this filter, and appends the required Sieve modules to requiresModules.

QString MailFilter::icon() const

Returns The name of the icon to be used.

See also setIcon.

QString MailFilter::identifier() const

Returns the unique identifier of this filter.

bool MailFilter::isAutoNaming() const

Returns Tells, if an automatic name is used for the filter

bool MailFilter::isEmpty() const

Returns true if the pattern and the action list are empty.

bool MailFilter::isEnabled() const

Return if filter is enabled or not

QString MailFilter::name() const

Equivalent to pattern()->name(). Returns name of the filter

MailCommon::SearchPattern *MailFilter::pattern()

Provides a reference to the internal pattern. If you used the matches() function before, please convert to using myFilter->pattern()->matches() now.

const MailCommon::SearchPattern *MailFilter::pattern() const

Provides a reference to the internal pattern. If you used the matches() function before, please convert to using myFilter->pattern()->matches() now.

QString MailFilter::purify(bool removeAction = true)

Remove empty rules, and empty actions if removeAction is true. Returns a description of the invalid rules and actions.

bool MailFilter::readConfig(const KConfigGroup &config, bool interactive = false)

Initialize from the given config group. If interactive is true, the user may be asked to fix the filter. Returns true if the configuration needs to be written back.

MailCommon::SearchRule::RequiredPart MailFilter::requiredPart(const QString &id) const

Returns the required part from the item that is needed for the filter to operate on messages from the account id. See SearchRule::RequiredPart

void MailFilter::setApplicability(MailCommon::MailFilter::AccountType apply = All)

Set whether this filter should be applied on inbound messages for all accounts (apply == All) or inbound messages for all but IMAP accounts (apply == ButImap) or for a specified set of accounts only. Only applicable to filters that are applied on inbound messages.

See also applicability(), setApplyOnInbound, and setApplyOnAccount.

void MailFilter::setApplyBeforeOutbound(bool apply)

Set whether this filter should be applied on outbound messages before sending (apply == TRUE) or not. See applyOnOutbound applyOnInbound setApplyOnInbound

See also applyBeforeOutbound().

void MailFilter::setApplyOnAccount(const QString &id, bool apply = true)

Set whether this filter should be applied on inbound messages for the account with id (id), according to apply. Only applicable to filters that are only applied to a specified set of accounts.

See also setApplicability and applyOnAccount.

void MailFilter::setApplyOnAllFoldersInbound(bool apply)

Sets whether the filter should be applied on inbound emails in all folders, not just Inbox, according to apply.

See also applyOnAllFoldersInbound().

void MailFilter::setApplyOnExplicit(bool apply)

Set whether this filter should be applied on explicit (CTRL-J) filtering (apply == true) or not.

See also applyOnExplicit(), setApplyOnOutbound, applyOnInbound, and applyOnOutbound.

void MailFilter::setApplyOnInbound(bool apply)

Set whether this filter should be applied on inbound messages (apply == true) or not.

See also setApplyOnOutbound, applyOnInbound, and applyOnOutbound.

void MailFilter::setApplyOnOutbound(bool apply)

Set whether this filter should be applied on outbound messages (apply == true) or not. See applyOnOutbound applyOnInbound setApplyOnInbound

See also applyOnOutbound().

void MailFilter::setAutoNaming(bool useAutomaticNames)

Set the mode for using automatic naming for the filter to useAutomaticNames. If the feature is enabled, the name is derived from the first filter rule.

See also isAutoNaming().

void MailFilter::setConfigureShortcut(bool aShort)

Set whether this filter should be plugged into the filter menu, according to aShort.

See also configureShortcut().

void MailFilter::setConfigureToolbar(bool aTool)

Set whether this filter should be plugged into the toolbar, according to aTool. This can be done only if a shortcut is defined.

See also configureToolbar() and setConfigureShortcut.

void MailFilter::setEnabled(bool)

Enables or disables the filter.

See also isEnabled().

void MailFilter::setIcon(const QString &icon)

Set the icon to be used if plugged into the filter menu or toolbar. Default is the gear icon.

See also icon(), setConfigureShortcut, and setConfigureToolbar.

void MailFilter::setShortcut(const QKeySequence &shortcut)

Set the shortcut to be used if plugged into the filter menu or toolbar. Default is no shortcut.

See also shortcut(), setConfigureShortcut, and setConfigureToolbar.

void MailFilter::setToolbarName(const QString &toolbarName)

This sets the toolbar name for this filter to toolbarName. The toolbar name is the text to be displayed underneath the toolbar icon for this filter. This is usually the same as name(), expect when explicitly set by this function. This is useful if the normal filter mame is too long for the toolbar.

See also toolbarName and name.

const QKeySequence &MailFilter::shortcut() const

Returns The shortcut assigned to the filter.

See also setShortcut.

QString MailFilter::toolbarName() const

Returns The toolbar name of this filter.

See also setToolbarName.

void MailFilter::writeConfig(KConfigGroup &config, bool exportFilter) const

Write contents to the given config group. If exportFilter is true, the action arguments are written in their exportable form.