Mailcommon

kmfilterlistbox.h
1/*
2 SPDX-FileCopyrightText: 2014-2024 Laurent Montel <montel@kde.org>
3
4 SPDX-License-Identifier: GPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "search/searchpattern.h"
10#include <QGroupBox>
11#include <QList>
12#include <QListWidgetItem>
13class QListWidget;
14class QPushButton;
15class QModelIndex;
17/**
18 * This is a complex widget that is used to manipulate a mail program's filter
19 * list. It consists of an internal list of filters, which is a deep
20 * copy of the list KMFilterMgr manages, a QListBox displaying that list,
21 * and a few buttons used to create new filters, delete them, rename them
22 * and change the order of filters.
23 *
24 * It does not provide means to change the actual filter (besides the name),
25 * but relies on auxiliary widgets (SearchPatternEdit and KMFilterActionEdit)
26 * to do that.
27 *
28 * Communication with this widget is quite easy: simply create an instance,
29 * connect the signals filterSelected, resetWidgets and applyWidgets with
30 * a slot that does the right thing and there you go...
31 *
32 * This widget will operate on it's own copy of the filter list as
33 * long as you don't call slotApplyFilterChanges. It will then
34 * transfer the altered filter list back to KMFilterMgr.
35 *
36 * @short A complex widget that allows managing a list of MailCommon::MailFilter's.
37 * @author Marc Mutz <mutz@kde.org>, based upon work by Stefan Taferner <taferner@kde.org>.
38 * @see MailCommon::MailFilter KMFilterDialog KMFilterActionEdit SearchPatternEdit
39 */
40
41namespace MailCommon
42{
43class MailFilter;
44
45class QListWidgetFilterItem : public QListWidgetItem
46{
47public:
48 explicit QListWidgetFilterItem(const QString &text, QListWidget *parent = nullptr);
49 ~QListWidgetFilterItem() override;
50
51 void setFilter(MailCommon::MailFilter *filter);
52 [[nodiscard]] MailCommon::MailFilter *filter() const;
53
54private:
55 MailCommon::MailFilter *mFilter = nullptr;
56};
57
58class KMFilterListBox : public QGroupBox
59{
61public:
62 /**
63 * Constructor.
64 */
65 explicit KMFilterListBox(const QString &title, QWidget *widget = nullptr);
66
67 /**
68 * Destructor.
69 */
70 ~KMFilterListBox() override;
71
72 /**
73 * Called from KMFilterDialog. Creates a new filter and presets
74 * the first rule with "field equals value". It's there mainly to
75 * support "rapid filter creation" from a context menu. You should
76 * instead call KMFilterMgr::createFilter.
77 * @see KMFilterMgr::createFilter KMFilterDialog::createFilter
78 */
79 void createFilter(const QByteArray &field, const QString &value);
80
81 /**
82 * Loads the filter list and selects the first filter. Should be
83 * called when all signals are connected properly. If createDummyFilter
84 * is true, an empty filter is created to improve the usability of the
85 * dialog in case no filter has been defined so far.
86 */
87 void loadFilterList(bool createDummyFilter);
88
89 void insertFilter(MailCommon::MailFilter *aFilter);
90
91 void appendFilter(MailCommon::MailFilter *aFilter);
92
93 /**
94 * Returns a list of _copies_ of the current list of filters.
95 * The list owns the contents and thus the caller needs to clean them up.
96 * @param closeAfterSaving If @c true user is given option to continue editing
97 * after being warned about invalid filters. Otherwise, user is just warned.
98 * @param wasCanceled If @c true then the operation was canceled.
99 */
100 QList<MailCommon::MailFilter *> filtersForSaving(bool closeAfterSaving, bool &wasCanceled) const;
101
102 QStringList selectedFilterId(SearchRule::RequiredPart &requiredPart, const QString &resource) const;
103
105 /**
106 * Emitted when a new filter has been selected by the user or if the
107 * current filter has changed after a 'new' or 'delete' operation.
108 */
109 void filterSelected(MailCommon::MailFilter *filter);
110
111 /**
112 * Emitted when this widget wants the edit widgets to let go of
113 * their filter reference. Everyone holding a reference to a filter
114 * should update it from the contents of the widgets used to edit
115 * it and set their internal reference to 0.
116 */
117 void resetWidgets();
118
119 /**
120 * Emitted when this widget wants the edit widgets to apply the changes
121 * to the current filter.
122 */
123 void applyWidgets();
124
125 /**
126 * Emitted when the user decides to continue editing after being warned
127 * about invalid filters.
128 */
129 void abortClosing() const;
130
131 /**
132 * Emitted when a new filter is created.
133 */
134 void filterCreated();
135
136 /**
137 * Emitted when a filter is deleted.
138 */
139 void filterRemoved(const QList<MailCommon::MailFilter *> &filter);
140
141 /**
142 * Emitted when a filter is updated (e.g. renamed).
143 */
144 void filterUpdated(MailCommon::MailFilter *filter);
145
146 /**
147 * Emitted whenever the order in which the filters are displayed is changed.
148 */
149 void filterOrderAltered();
150
151public Q_SLOTS:
152 /**
153 * Called when the name of a filter might have changed (e.g. through
154 * changing the first rule in SearchPatternEdit). Updates the corresponding
155 * entry in the listbox and (if necessary) auto-names the filter.
156 */
157 void slotUpdateFilterName();
158
159 void slotAccepted();
160 void slotApplied();
161
162protected Q_SLOTS:
163 /**
164 * Called when the user clicks on a filter in the filter list.
165 * Calculates the corresponding filter and emits the filterSelected signal.
166 */
167 void slotSelected(int aIdx);
168
169 /**
170 * Called when the user clicks the 'New' button.
171 * Creates a new empty filter just before the current one.
172 */
173 void slotNew();
174
175 /**
176 * Called when the user clicks the 'Copy' button. Creates a copy
177 * of the current filter and inserts it just before the current one.
178 */
179 void slotCopy();
180
181 /**
182 * Called when the user clicks the 'Delete' button. Deletes the
183 * current filter.
184 */
185 void slotDelete();
186
187 /**
188 * Called when the user clicks the 'Up' button. Moves the current
189 * filter up one line.
190 */
191 void slotUp();
192
193 /**
194 * Called when the user clicks the 'Down' button. Moves the current
195 * filter down one line.
196 */
197 void slotDown();
198
199 /**
200 * Called when the user clicks the 'Rename' button. Pops up a
201 * dialog prompting to enter the new name.
202 */
203 void slotRename();
204
205 void slotRowsMoved(const QModelIndex &, int, int, const QModelIndex &, int);
206
207 /**
208 * Called when the user clicks the 'Top' button. Moves the current
209 * filter to top.
210 */
211 void slotTop();
212
213 /**
214 * Called when the user clicks the 'Bottom' button. Moves the current
215 * filter to bottom.
216 */
217 void slotBottom();
218
219 void slotFilterEnabledChanged(QListWidgetItem *item);
220
221 void slotSelectionChanged();
222
223protected:
224 /** The listbox displaying the filter list. */
225 QListWidget *mListWidget = nullptr;
226
227 /** The various action buttons. */
228 QPushButton *mBtnNew = nullptr;
229 QPushButton *mBtnCopy = nullptr;
230 QPushButton *mBtnDelete = nullptr;
231 QPushButton *mBtnUp = nullptr;
232 QPushButton *mBtnDown = nullptr;
233 QPushButton *mBtnRename = nullptr;
234 QPushButton *mBtnTop = nullptr;
235 QPushButton *mBtnBottom = nullptr;
236 KListWidgetSearchLine *mSearchListWidget = nullptr;
237 bool eventFilter(QObject *obj, QEvent *event) override;
238
239private:
240 void applyFilterChanged(bool closeAfterSaving);
241 void enableControls();
242 bool itemIsValid(QListWidgetItem *item) const;
243 QList<QListWidgetItem *> selectedFilter();
244 void swapNeighbouringFilters(int untouchedOne, int movedOne);
245};
246}
The MailFilter class.
Definition mailfilter.h:29
RequiredPart
Possible required parts.
Definition searchrule.h:68
The filter dialog.
virtual bool event(QEvent *e) override
QString text() const const
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:02:04 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.