1/* This file is part of the KDE libraries
2 Copyright (C) 2000 David Faure <faure@kde.org>, Alexander Neundorf <neundorf@kde.org>
3 (C) 2010 Sebastian Trueg <trueg@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KEDITLISTWIDGET_H
22#define KEDITLISTWIDGET_H
23
24#include <kdeui_export.h>
25
26#include <QtGui/QWidget>
27#include <QtGui/QStringListModel>
28
29class KLineEdit;
30class KComboBox;
31class QListView;
32class QPushButton;
33
34class KEditListWidgetPrivate;
35/**
36 * An editable listbox
37 *
38 * This class provides an editable listbox, this means
39 * a listbox which is accompanied by a line edit to enter new
40 * items into the listbox and pushbuttons to add and remove
41 * items from the listbox and two buttons to move items up and down.
42 *
43 * \image html keditlistbox.png "KDE Edit List Box Widget"
44 *
45 *
46 * @since 4.6
47 */
48class KDEUI_EXPORT KEditListWidget : public QWidget
49{
50 Q_OBJECT
51
52 Q_FLAGS( Buttons )
53 Q_PROPERTY( Buttons buttons READ buttons WRITE setButtons )
54 Q_PROPERTY( QStringList items READ items WRITE setItems NOTIFY changed USER true )
55 Q_PROPERTY( bool checkAtEntering READ checkAtEntering WRITE setCheckAtEntering )
56
57public:
58 class CustomEditorPrivate;
59
60 /**
61 * Custom editor class
62 **/
63 class KDEUI_EXPORT CustomEditor
64 {
65 public:
66 CustomEditor();
67 CustomEditor( QWidget *repWidget, KLineEdit *edit );
68 CustomEditor( KComboBox *combo );
69 virtual ~CustomEditor();
70
71 void setRepresentationWidget( QWidget *repWidget );
72 void setLineEdit( KLineEdit *edit );
73
74 virtual QWidget *representationWidget() const;
75 virtual KLineEdit *lineEdit() const;
76
77 private:
78 friend class CustomEditorPrivate;
79 CustomEditorPrivate *const d;
80
81 Q_DISABLE_COPY(CustomEditor)
82 };
83
84 public:
85
86 /**
87 * Enumeration of the buttons, the listbox offers. Specify them in the
88 * constructor in the buttons parameter, or in setButtons.
89 */
90 enum Button {
91 Add = 0x0001,
92 Remove = 0x0002,
93 UpDown = 0x0004,
94 All = Add | Remove | UpDown
95 };
96
97 Q_DECLARE_FLAGS( Buttons, Button )
98
99 /**
100 * Create an editable listbox.
101 */
102 explicit KEditListWidget(QWidget *parent = 0);
103
104 /**
105 * Constructor which allows to use a custom editing widget
106 * instead of the standard KLineEdit widget. E.g. you can use a
107 * KUrlRequester or a KComboBox as input widget. The custom
108 * editor must consist of a lineedit and optionally another widget that
109 * is used as representation. A KComboBox or a KUrlRequester have a
110 * KLineEdit as child-widget for example, so the KComboBox is used as
111 * the representation widget.
112 *
113 * @see KUrlRequester::customEditor(), setCustomEditor
114 */
115 KEditListWidget( const CustomEditor &customEditor,
116 QWidget *parent = 0,
117 bool checkAtEntering = false,
118 Buttons buttons = All );
119
120 virtual ~KEditListWidget();
121
122 /**
123 * Return a pointer to the embedded QListView.
124 */
125 QListView* listView() const;
126 /**
127 * Return a pointer to the embedded KLineEdit.
128 */
129 KLineEdit* lineEdit() const;
130 /**
131 * Return a pointer to the Add button
132 */
133 QPushButton* addButton() const;
134 /**
135 * Return a pointer to the Remove button
136 */
137 QPushButton* removeButton() const;
138 /**
139 * Return a pointer to the Up button
140 */
141 QPushButton* upButton() const;
142 /**
143 * Return a pointer to the Down button
144 */
145 QPushButton* downButton() const;
146
147 /**
148 * See Q3ListBox::count()
149 */
150 int count() const;
151 /**
152 * See Q3ListBox::insertStringList()
153 */
154 void insertStringList(const QStringList& list, int index=-1);
155 /**
156 * See Q3ListBox::insertItem()
157 */
158 void insertItem(const QString& text, int index=-1);
159 /**
160 * Clears both the listbox and the line edit.
161 */
162 void clear();
163 /**
164 * See Q3ListBox::text()
165 */
166 QString text(int index) const;
167 /**
168 * See Q3ListBox::currentItem()
169 */
170 int currentItem() const;
171 /**
172 * See Q3ListBox::currentText()
173 */
174 QString currentText() const;
175
176 /**
177 * @returns a stringlist of all items in the listbox
178 */
179 QStringList items() const;
180
181 /**
182 * Clears the listbox and sets the contents to @p items
183 */
184 void setItems(const QStringList& items);
185
186 /**
187 * Returns which buttons are visible
188 */
189 Buttons buttons() const;
190
191 /**
192 * Specifies which buttons should be visible
193 */
194 void setButtons( Buttons buttons );
195
196 /**
197 * If @p check is true, after every character you type
198 * in the line edit KEditListWidget will enable or disable
199 * the Add-button, depending whether the current content of the
200 * line edit is already in the listbox. Maybe this can become a
201 * performance hit with large lists on slow machines.
202 * If @p check is false,
203 * it will be checked if you press the Add-button. It is not
204 * possible to enter items twice into the listbox.
205 * Default is false.
206 */
207 void setCheckAtEntering(bool check);
208
209 /**
210 * Returns true if check at entering is enabled.
211 */
212 bool checkAtEntering();
213
214 /**
215 * Allows to use a custom editing widget
216 * instead of the standard KLineEdit widget. E.g. you can use a
217 * KUrlRequester or a KComboBox as input widget. The custom
218 * editor must consist of a lineedit and optionally another widget that
219 * is used as representation. A KComboBox or a KUrlRequester have a
220 * KLineEdit as child-widget for example, so the KComboBox is used as
221 * the representation widget.
222 */
223 void setCustomEditor( const CustomEditor& editor );
224
225 /**
226 * Reimplented for interal reasons. The API is not affected.
227 */
228 bool eventFilter( QObject* o, QEvent* e );
229
230 Q_SIGNALS:
231 void changed();
232
233 /**
234 * This signal is emitted when the user adds a new string to the list,
235 * the parameter is the added string.
236 */
237 void added( const QString & text );
238
239 /**
240 * This signal is emitted when the user removes a string from the list,
241 * the parameter is the removed string.
242 */
243 void removed( const QString & text );
244
245 private Q_SLOTS:
246 void moveItemUp();
247 void moveItemDown();
248 void addItem();
249 void removeItem();
250 void enableMoveButtons(const QModelIndex&, const QModelIndex&);
251 void typedSomething(const QString& text);
252 void slotSelectionChanged( const QItemSelection& selected, const QItemSelection& deselected );
253
254 private:
255 friend class KEditListWidgetPrivate;
256 KEditListWidgetPrivate* const d;
257
258 Q_DISABLE_COPY(KEditListWidget)
259};
260
261Q_DECLARE_OPERATORS_FOR_FLAGS(KEditListWidget::Buttons)
262
263#endif
264