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

source code of kwidgetsaddons/src/keditlistwidget.h