KWidgetsAddons

keditlistwidget.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
4  SPDX-FileCopyrightText: 2000 Alexander Neundorf <[email protected]>
5  SPDX-FileCopyrightText: 2010 Sebastian Trueg <[email protected]>
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 
18 class QLineEdit;
19 class QComboBox;
20 class QListView;
21 class QPushButton;
22 class 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  */
38 class 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 
46 public:
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 
71 public:
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 
226 Q_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 
241 private 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 
250 private:
251  friend class KEditListWidgetPrivate;
252  std::unique_ptr<class KEditListWidgetPrivate> const d;
253 
254  Q_DISABLE_COPY(KEditListWidget)
255 };
256 
257 Q_DECLARE_OPERATORS_FOR_FLAGS(KEditListWidget::Buttons)
258 
259 #endif
Q_PROPERTY(...)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 03:59:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.