1 /****************************************************************************
2 **
3 ** Copyright (C) 2016 The Qt Company Ltd.
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of the QtWidgets module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see https://www.qt.io/terms-conditions. For further
15 ** information use the contact form at https://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 3 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL3 included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 3 requirements
23 ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24 **
25 ** GNU General Public License Usage
26 ** Alternatively, this file may be used under the terms of the GNU
27 ** General Public License version 2.0 or (at your option) the GNU General
28 ** Public license version 3 or any later version approved by the KDE Free
29 ** Qt Foundation. The licenses are as published by the Free Software
30 ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31 ** included in the packaging of this file. Please review the following
32 ** information to ensure the GNU General Public License requirements will
33 ** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34 ** https://www.gnu.org/licenses/gpl-3.0.html.
35 **
36 ** $QT_END_LICENSE$
37 **
38 ****************************************************************************/
39
40 #ifndef QCOMBOBOX_H
41 #define QCOMBOBOX_H
42
43 #include <QtWidgets/qtwidgetsglobal.h>
44 #include <QtWidgets/qwidget.h>
45 #include <QtWidgets/qabstractitemdelegate.h>
46 #include <QtCore/qabstractitemmodel.h>
47 #include <QtCore/qvariant.h>
48 #include <QtGui/qvalidator.h>
49
50 QT_REQUIRE_CONFIG(combobox);
51
52 QT_BEGIN_NAMESPACE
53
54 class QAbstractItemView;
55 class QLineEdit;
56 class QComboBoxPrivate;
57 class QCompleter;
58
59 class Q_WIDGETS_EXPORT QComboBox : public QWidget
60 {
61 Q_OBJECT
62
63 Q_PROPERTY(bool editable READ isEditable WRITE setEditable)
64 Q_PROPERTY(int count READ count)
65 Q_PROPERTY(QString currentText READ currentText WRITE setCurrentText NOTIFY currentTextChanged USER true)
66 Q_PROPERTY(int currentIndex READ currentIndex WRITE setCurrentIndex NOTIFY currentIndexChanged)
67 Q_PROPERTY(QVariant currentData READ currentData)
68 Q_PROPERTY(int maxVisibleItems READ maxVisibleItems WRITE setMaxVisibleItems)
69 Q_PROPERTY(int maxCount READ maxCount WRITE setMaxCount)
70 Q_PROPERTY(InsertPolicy insertPolicy READ insertPolicy WRITE setInsertPolicy)
71 Q_PROPERTY(SizeAdjustPolicy sizeAdjustPolicy READ sizeAdjustPolicy WRITE setSizeAdjustPolicy)
72 Q_PROPERTY(int minimumContentsLength READ minimumContentsLength WRITE setMinimumContentsLength)
73 Q_PROPERTY(QSize iconSize READ iconSize WRITE setIconSize)
74 Q_PROPERTY(QString placeholderText READ placeholderText WRITE setPlaceholderText)
75
76 #if QT_CONFIG(completer)
77 #if QT_DEPRECATED_SINCE(5, 13)
78 Q_PROPERTY(bool autoCompletion READ autoCompletion WRITE setAutoCompletion DESIGNABLE false)
79 Q_PROPERTY(Qt::CaseSensitivity autoCompletionCaseSensitivity READ autoCompletionCaseSensitivity WRITE setAutoCompletionCaseSensitivity DESIGNABLE false)
80 #endif
81 #endif // QT_CONFIG(completer)
82
83 Q_PROPERTY(bool duplicatesEnabled READ duplicatesEnabled WRITE setDuplicatesEnabled)
84 Q_PROPERTY(bool frame READ hasFrame WRITE setFrame)
85 Q_PROPERTY(int modelColumn READ modelColumn WRITE setModelColumn)
86
87 public:
88 explicit QComboBox(QWidget *parent = nullptr);
89 ~QComboBox();
90
91 int maxVisibleItems() const;
92 void setMaxVisibleItems(int maxItems);
93
94 int count() const;
95 void setMaxCount(int max);
96 int maxCount() const;
97
98 #if QT_CONFIG(completer)
99 #if QT_DEPRECATED_SINCE(5, 13)
100 QT_DEPRECATED_X("Use completer() instead.")
101 bool autoCompletion() const;
102 QT_DEPRECATED_X("Use setCompleter() instead.")
103 void setAutoCompletion(bool enable);
104 QT_DEPRECATED_X("Use completer()->caseSensitivity() instead.")
105 Qt::CaseSensitivity autoCompletionCaseSensitivity() const;
106 QT_DEPRECATED_X("Use completer()->setCaseSensitivity() instead.")
107 void setAutoCompletionCaseSensitivity(Qt::CaseSensitivity sensitivity);
108 #endif
109 #endif
110
111 bool duplicatesEnabled() const;
112 void setDuplicatesEnabled(bool enable);
113
114 void setFrame(bool);
115 bool hasFrame() const;
116
117 inline int findText(const QString &text,
118 Qt::MatchFlags flags = static_cast<Qt::MatchFlags>(Qt::MatchExactly|Qt::MatchCaseSensitive)) const
119 { return findData(text, Qt::DisplayRole, flags); }
120 int findData(const QVariant &data, int role = Qt::UserRole,
121 Qt::MatchFlags flags = static_cast<Qt::MatchFlags>(Qt::MatchExactly|Qt::MatchCaseSensitive)) const;
122
123 enum InsertPolicy {
124 NoInsert,
125 InsertAtTop,
126 InsertAtCurrent,
127 InsertAtBottom,
128 InsertAfterCurrent,
129 InsertBeforeCurrent,
130 InsertAlphabetically
131 };
132 Q_ENUM(InsertPolicy)
133
134 InsertPolicy insertPolicy() const;
135 void setInsertPolicy(InsertPolicy policy);
136
137 enum SizeAdjustPolicy {
138 AdjustToContents,
139 AdjustToContentsOnFirstShow,
140 #if QT_DEPRECATED_SINCE(5, 15)
141 AdjustToMinimumContentsLength Q_DECL_ENUMERATOR_DEPRECATED_X(
142 "Use AdjustToContents or AdjustToContentsOnFirstShow"), // ### Qt 6: remove
143 #endif
144 AdjustToMinimumContentsLengthWithIcon = AdjustToContentsOnFirstShow + 2
145 };
146 Q_ENUM(SizeAdjustPolicy)
147
148 SizeAdjustPolicy sizeAdjustPolicy() const;
149 void setSizeAdjustPolicy(SizeAdjustPolicy policy);
150 int minimumContentsLength() const;
151 void setMinimumContentsLength(int characters);
152 QSize iconSize() const;
153 void setIconSize(const QSize &size);
154
155 void setPlaceholderText(const QString &placeholderText);
156 QString placeholderText() const;
157
158 bool isEditable() const;
159 void setEditable(bool editable);
160 void setLineEdit(QLineEdit *edit);
161 QLineEdit *lineEdit() const;
162 #ifndef QT_NO_VALIDATOR
163 void setValidator(const QValidator *v);
164 const QValidator *validator() const;
165 #endif
166
167 #if QT_CONFIG(completer)
168 void setCompleter(QCompleter *c);
169 QCompleter *completer() const;
170 #endif
171
172 QAbstractItemDelegate *itemDelegate() const;
173 void setItemDelegate(QAbstractItemDelegate *delegate);
174
175 QAbstractItemModel *model() const;
176 void setModel(QAbstractItemModel *model);
177
178 QModelIndex rootModelIndex() const;
179 void setRootModelIndex(const QModelIndex &index);
180
181 int modelColumn() const;
182 void setModelColumn(int visibleColumn);
183
184 int currentIndex() const;
185 QString currentText() const;
186 QVariant currentData(int role = Qt::UserRole) const;
187
188 QString itemText(int index) const;
189 QIcon itemIcon(int index) const;
190 QVariant itemData(int index, int role = Qt::UserRole) const;
191
192 inline void addItem(const QString &text, const QVariant &userData = QVariant());
193 inline void addItem(const QIcon &icon, const QString &text,
194 const QVariant &userData = QVariant());
addItems(const QStringList & texts)195 inline void addItems(const QStringList &texts)
196 { insertItems(count(), texts); }
197
198 inline void insertItem(int index, const QString &text, const QVariant &userData = QVariant());
199 void insertItem(int index, const QIcon &icon, const QString &text,
200 const QVariant &userData = QVariant());
201 void insertItems(int index, const QStringList &texts);
202 void insertSeparator(int index);
203
204 void removeItem(int index);
205
206 void setItemText(int index, const QString &text);
207 void setItemIcon(int index, const QIcon &icon);
208 void setItemData(int index, const QVariant &value, int role = Qt::UserRole);
209
210 QAbstractItemView *view() const;
211 void setView(QAbstractItemView *itemView);
212
213 QSize sizeHint() const override;
214 QSize minimumSizeHint() const override;
215
216 virtual void showPopup();
217 virtual void hidePopup();
218
219 bool event(QEvent *event) override;
220 QVariant inputMethodQuery(Qt::InputMethodQuery) const override;
221 Q_INVOKABLE QVariant inputMethodQuery(Qt::InputMethodQuery query, const QVariant &argument) const;
222
223 public Q_SLOTS:
224 void clear();
225 void clearEditText();
226 void setEditText(const QString &text);
227 void setCurrentIndex(int index);
228 void setCurrentText(const QString &text);
229
230 Q_SIGNALS:
231 void editTextChanged(const QString &);
232 void activated(int index);
233 void textActivated(const QString &);
234 void highlighted(int index);
235 void textHighlighted(const QString &);
236 void currentIndexChanged(int index);
237 #if QT_DEPRECATED_SINCE(5, 15)
238 QT_DEPRECATED_VERSION_X_5_15(
239 "Use currentIndexChanged(int) instead, and get the text using itemText(index)")
240 void currentIndexChanged(const QString &);
241 #endif
242 void currentTextChanged(const QString &);
243 #if QT_DEPRECATED_SINCE(5, 15)
244 QT_DEPRECATED_VERSION_X(5, 15, "Use textActivated() instead")
245 void activated(const QString &);
246 QT_DEPRECATED_VERSION_X(5, 15, "Use textHighlighted() instead")
247 void highlighted(const QString &);
248 #endif
249
250 protected:
251 void focusInEvent(QFocusEvent *e) override;
252 void focusOutEvent(QFocusEvent *e) override;
253 void changeEvent(QEvent *e) override;
254 void resizeEvent(QResizeEvent *e) override;
255 void paintEvent(QPaintEvent *e) override;
256 void showEvent(QShowEvent *e) override;
257 void hideEvent(QHideEvent *e) override;
258 void mousePressEvent(QMouseEvent *e) override;
259 void mouseReleaseEvent(QMouseEvent *e) override;
260 void keyPressEvent(QKeyEvent *e) override;
261 void keyReleaseEvent(QKeyEvent *e) override;
262 #if QT_CONFIG(wheelevent)
263 void wheelEvent(QWheelEvent *e) override;
264 #endif
265 #ifndef QT_NO_CONTEXTMENU
266 void contextMenuEvent(QContextMenuEvent *e) override;
267 #endif // QT_NO_CONTEXTMENU
268 void inputMethodEvent(QInputMethodEvent *) override;
269 void initStyleOption(QStyleOptionComboBox *option) const;
270
271
272 protected:
273 QComboBox(QComboBoxPrivate &, QWidget *);
274
275 private:
276 Q_DECLARE_PRIVATE(QComboBox)
277 Q_DISABLE_COPY(QComboBox)
278 Q_PRIVATE_SLOT(d_func(), void _q_itemSelected(const QModelIndex &item))
279 Q_PRIVATE_SLOT(d_func(), void _q_emitHighlighted(const QModelIndex &))
280 Q_PRIVATE_SLOT(d_func(), void _q_emitCurrentIndexChanged(const QModelIndex &index))
281 Q_PRIVATE_SLOT(d_func(), void _q_editingFinished())
282 Q_PRIVATE_SLOT(d_func(), void _q_returnPressed())
283 Q_PRIVATE_SLOT(d_func(), void _q_resetButton())
284 Q_PRIVATE_SLOT(d_func(), void _q_dataChanged(const QModelIndex &, const QModelIndex &))
285 Q_PRIVATE_SLOT(d_func(), void _q_updateIndexBeforeChange())
286 Q_PRIVATE_SLOT(d_func(), void _q_rowsInserted(const QModelIndex & parent, int start, int end))
287 Q_PRIVATE_SLOT(d_func(), void _q_rowsRemoved(const QModelIndex & parent, int start, int end))
288 Q_PRIVATE_SLOT(d_func(), void _q_modelDestroyed())
289 Q_PRIVATE_SLOT(d_func(), void _q_modelReset())
290 #if QT_CONFIG(completer)
291 Q_PRIVATE_SLOT(d_func(), void _q_completerActivated(const QModelIndex &index))
292 #endif
293 };
294
addItem(const QString & atext,const QVariant & auserData)295 inline void QComboBox::addItem(const QString &atext, const QVariant &auserData)
296 { insertItem(count(), atext, auserData); }
addItem(const QIcon & aicon,const QString & atext,const QVariant & auserData)297 inline void QComboBox::addItem(const QIcon &aicon, const QString &atext,
298 const QVariant &auserData)
299 { insertItem(count(), aicon, atext, auserData); }
300
insertItem(int aindex,const QString & atext,const QVariant & auserData)301 inline void QComboBox::insertItem(int aindex, const QString &atext,
302 const QVariant &auserData)
303 { insertItem(aindex, QIcon(), atext, auserData); }
304
305 QT_END_NAMESPACE
306
307 #endif // QCOMBOBOX_H
308