1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
4 SPDX-FileCopyrightText: 2000 Alexander Neundorf <neundorf@kde.org>
5 SPDX-FileCopyrightText: 2010 Sebastian Trueg <trueg@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KEDITLISTWIDGET_H
11#define KEDITLISTWIDGET_H
12
13#include <kwidgetsaddons_export.h>
14
15#include <QWidget>
16#include <memory>
17
18class QLineEdit;
19class QComboBox;
20class QListView;
21class QPushButton;
22class QItemSelection;
23
24/*!
25 * \class KEditListWidget
26 * \inmodule KWidgetsAddons
27 *
28 * \brief An editable listbox.
29 *
30 * This class provides an editable listbox, this means
31 * a listbox which is accompanied by a line edit to enter new
32 * items into the listbox and pushbuttons to add and remove
33 * items from the listbox and two buttons to move items up and down.
34 *
35 * \image keditlistbox.png "KEditListWidget"
36 *
37 * \since 4.6
38 */
39class KWIDGETSADDONS_EXPORT KEditListWidget : public QWidget
40{
41 Q_OBJECT
42
43 /*!
44 * \property KEditListWidget::buttons
45 */
46 Q_PROPERTY(Buttons buttons READ buttons WRITE setButtons)
47
48 /*!
49 * \property KEditListWidget::items
50 */
51 Q_PROPERTY(QStringList items READ items WRITE setItems NOTIFY changed USER true)
52
53 /*!
54 * \property KEditListWidget::checkAtEntering
55 */
56 Q_PROPERTY(bool checkAtEntering READ checkAtEntering WRITE setCheckAtEntering)
57
58public:
59 /*!
60 * \class KEditListWidget::CustomEditor
61 * \inheaderfile KEditListWidget
62 *
63 * \brief Custom editor class
64 */
65 class KWIDGETSADDONS_EXPORT CustomEditor
66 {
67 public:
68 /*!
69 *
70 */
71 CustomEditor();
72 CustomEditor(QWidget *repWidget, QLineEdit *edit);
73 CustomEditor(QComboBox *combo);
74 virtual ~CustomEditor();
75
76 /*!
77 *
78 */
79 void setRepresentationWidget(QWidget *repWidget);
80
81 /*!
82 *
83 */
84 void setLineEdit(QLineEdit *edit);
85
86 /*!
87 *
88 */
89 virtual QWidget *representationWidget() const;
90
91 /*!
92 *
93 */
94 virtual QLineEdit *lineEdit() const;
95
96 private:
97 friend class KEditListWidgetCustomEditorPrivate;
98 std::unique_ptr<class KEditListWidgetCustomEditorPrivate> const d;
99
100 Q_DISABLE_COPY(CustomEditor)
101 };
102
103public:
104 /*!
105 * Enumeration of the buttons, the listbox offers. Specify them in the
106 * constructor in the buttons parameter, or in setButtons.
107 *
108 * \value Add
109 * \value Remove
110 * \value UpDown
111 * \value All
112 */
113 enum Button {
114 Add = 0x0001,
115 Remove = 0x0002,
116 UpDown = 0x0004,
117 All = Add | Remove | UpDown,
118 };
119 Q_DECLARE_FLAGS(Buttons, Button)
120 Q_FLAG(Buttons)
121
122 /*!
123 * Create an editable listbox.
124 */
125 explicit KEditListWidget(QWidget *parent = nullptr);
126
127 /*!
128 * Constructor which allows to use a custom editing widget
129 * instead of the standard QLineEdit widget. E.g. you can use a
130 * KUrlRequester or a QComboBox as input widget. The custom
131 * editor must consist of a lineedit and optionally another widget that
132 * is used as representation. A QComboBox or a KUrlRequester have a
133 * QLineEdit as child-widget for example, so the QComboBox is used as
134 * the representation widget.
135 *
136 * \sa KUrlRequester::customEditor(), setCustomEditor
137 */
138 KEditListWidget(const CustomEditor &customEditor, QWidget *parent = nullptr, bool checkAtEntering = false, Buttons buttons = All);
139
140 ~KEditListWidget() override;
141
142 /*!
143 * Returns a pointer to the embedded QListView.
144 */
145 QListView *listView() const;
146 /*!
147 * Returns a pointer to the embedded QLineEdit.
148 */
149 QLineEdit *lineEdit() const;
150 /*!
151 * Returns a pointer to the Add button
152 */
153 QPushButton *addButton() const;
154 /*!
155 * Returns a pointer to the Remove button
156 */
157 QPushButton *removeButton() const;
158 /*!
159 * Returns a pointer to the Up button
160 */
161 QPushButton *upButton() const;
162 /*!
163 * Returns a pointer to the Down button
164 */
165 QPushButton *downButton() const;
166
167 /*!
168 * Returns the count of elements in the list
169 */
170 int count() const;
171
172 /*!
173 * Inserts a \a list of elements from the \a index element
174 * If \a index is negative, the elements will be appended
175 */
176 void insertStringList(const QStringList &list, int index = -1);
177
178 /*!
179 * Inserts a \a text element at the \a index position
180 * If \a index is negative, the element will be appended
181 */
182 void insertItem(const QString &text, int index = -1);
183
184 /*!
185 * Clears both the listbox and the line edit.
186 */
187 void clear();
188
189 /*!
190 * Returns the text at the \a index position
191 */
192 QString text(int index) const;
193
194 /*!
195 * Returns the currently selected item
196 */
197 int currentItem() const;
198
199 /*!
200 * Returns the currently selected item's text
201 */
202 QString currentText() const;
203
204 /*!
205 * Returns a list with the text of all items in the listbox
206 */
207 QStringList items() const;
208
209 /*!
210 * Clears the listbox and sets the contents to \a items
211 */
212 void setItems(const QStringList &items);
213
214 /*!
215 * Returns which buttons are visible
216 */
217 Buttons buttons() const;
218
219 /*!
220 * Specifies which \a buttons are visible
221 */
222 void setButtons(Buttons buttons);
223
224 /*!
225 * If \a check is true, after every character you type
226 * in the line edit KEditListWidget will enable or disable
227 * the Add-button, depending whether the current content of the
228 * line edit is already in the listbox. Maybe this can become a
229 * performance hit with large lists on slow machines.
230 *
231 * If \a check is false,
232 * it will be checked if you press the Add-button. It is not
233 * possible to enter items twice into the listbox.
234 * Default is false.
235 */
236 void setCheckAtEntering(bool check);
237
238 /*!
239 * Returns true if check at entering is enabled.
240 */
241 bool checkAtEntering();
242
243 /*!
244 * Allows to use a custom editing widget
245 * instead of the standard QLineEdit widget. E.g. you can use a
246 * KUrlRequester or a QComboBox as input widget. The custom
247 * editor must consist of a lineedit and optionally another widget that
248 * is used as representation. A QComboBox or a KUrlRequester have a
249 * QLineEdit as child-widget for example, so the QComboBox is used as
250 * the representation widget.
251 */
252 void setCustomEditor(const CustomEditor &editor);
253
254 bool eventFilter(QObject *o, QEvent *e) override;
255
256Q_SIGNALS:
257 void changed();
258
259 /*!
260 * This signal is emitted when the user adds a new string to the list,
261 * the parameter is the added string.
262 */
263 void added(const QString &text);
264
265 /*!
266 * This signal is emitted when the user removes a string from the list,
267 * the parameter is the removed string.
268 */
269 void removed(const QString &text);
270
271private Q_SLOTS:
272 KWIDGETSADDONS_NO_EXPORT void moveItemUp();
273 KWIDGETSADDONS_NO_EXPORT void moveItemDown();
274 KWIDGETSADDONS_NO_EXPORT void addItem();
275 KWIDGETSADDONS_NO_EXPORT void removeItem();
276 KWIDGETSADDONS_NO_EXPORT void enableMoveButtons(const QModelIndex &, const QModelIndex &);
277 KWIDGETSADDONS_NO_EXPORT void typedSomething(const QString &text);
278 KWIDGETSADDONS_NO_EXPORT void slotSelectionChanged(const QItemSelection &selected, const QItemSelection &deselected);
279
280private:
281 friend class KEditListWidgetPrivate;
282 std::unique_ptr<class KEditListWidgetPrivate> const d;
283
284 Q_DISABLE_COPY(KEditListWidget)
285};
286
287Q_DECLARE_OPERATORS_FOR_FLAGS(KEditListWidget::Buttons)
288
289#endif
290

source code of kwidgetsaddons/src/keditlistwidget.h