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
50QT_REQUIRE_CONFIG(combobox);
51
52QT_BEGIN_NAMESPACE
53
54class QAbstractItemView;
55class QLineEdit;
56class QComboBoxPrivate;
57class QCompleter;
58
59class 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
75#if QT_CONFIG(completer)
76#if QT_DEPRECATED_SINCE(5, 13)
77 Q_PROPERTY(bool autoCompletion READ autoCompletion WRITE setAutoCompletion DESIGNABLE false)
78 Q_PROPERTY(Qt::CaseSensitivity autoCompletionCaseSensitivity READ autoCompletionCaseSensitivity WRITE setAutoCompletionCaseSensitivity DESIGNABLE false)
79#endif
80#endif // QT_CONFIG(completer)
81
82 Q_PROPERTY(bool duplicatesEnabled READ duplicatesEnabled WRITE setDuplicatesEnabled)
83 Q_PROPERTY(bool frame READ hasFrame WRITE setFrame)
84 Q_PROPERTY(int modelColumn READ modelColumn WRITE setModelColumn)
85
86public:
87 explicit QComboBox(QWidget *parent = nullptr);
88 ~QComboBox();
89
90 int maxVisibleItems() const;
91 void setMaxVisibleItems(int maxItems);
92
93 int count() const;
94 void setMaxCount(int max);
95 int maxCount() const;
96
97#if QT_CONFIG(completer)
98#if QT_DEPRECATED_SINCE(5, 13)
99 QT_DEPRECATED_X("Use completer() instead.")
100 bool autoCompletion() const;
101 QT_DEPRECATED_X("Use setCompleter() instead.")
102 void setAutoCompletion(bool enable);
103 QT_DEPRECATED_X("Use completer()->caseSensitivity() instead.")
104 Qt::CaseSensitivity autoCompletionCaseSensitivity() const;
105 QT_DEPRECATED_X("Use completer()->setCaseSensitivity() instead.")
106 void setAutoCompletionCaseSensitivity(Qt::CaseSensitivity sensitivity);
107#endif
108#endif
109
110 bool duplicatesEnabled() const;
111 void setDuplicatesEnabled(bool enable);
112
113 void setFrame(bool);
114 bool hasFrame() const;
115
116 inline int findText(const QString &text,
117 Qt::MatchFlags flags = static_cast<Qt::MatchFlags>(Qt::MatchExactly|Qt::MatchCaseSensitive)) const
118 { return findData(text, Qt::DisplayRole, flags); }
119 int findData(const QVariant &data, int role = Qt::UserRole,
120 Qt::MatchFlags flags = static_cast<Qt::MatchFlags>(Qt::MatchExactly|Qt::MatchCaseSensitive)) const;
121
122 enum InsertPolicy {
123 NoInsert,
124 InsertAtTop,
125 InsertAtCurrent,
126 InsertAtBottom,
127 InsertAfterCurrent,
128 InsertBeforeCurrent,
129 InsertAlphabetically
130 };
131 Q_ENUM(InsertPolicy)
132
133 InsertPolicy insertPolicy() const;
134 void setInsertPolicy(InsertPolicy policy);
135
136 enum SizeAdjustPolicy {
137 AdjustToContents,
138 AdjustToContentsOnFirstShow,
139 AdjustToMinimumContentsLength, // ### Qt 6: remove
140 AdjustToMinimumContentsLengthWithIcon
141 };
142 Q_ENUM(SizeAdjustPolicy)
143
144 SizeAdjustPolicy sizeAdjustPolicy() const;
145 void setSizeAdjustPolicy(SizeAdjustPolicy policy);
146 int minimumContentsLength() const;
147 void setMinimumContentsLength(int characters);
148 QSize iconSize() const;
149 void setIconSize(const QSize &size);
150
151 bool isEditable() const;
152 void setEditable(bool editable);
153 void setLineEdit(QLineEdit *edit);
154 QLineEdit *lineEdit() const;
155#ifndef QT_NO_VALIDATOR
156 void setValidator(const QValidator *v);
157 const QValidator *validator() const;
158#endif
159
160#if QT_CONFIG(completer)
161 void setCompleter(QCompleter *c);
162 QCompleter *completer() const;
163#endif
164
165 QAbstractItemDelegate *itemDelegate() const;
166 void setItemDelegate(QAbstractItemDelegate *delegate);
167
168 QAbstractItemModel *model() const;
169 void setModel(QAbstractItemModel *model);
170
171 QModelIndex rootModelIndex() const;
172 void setRootModelIndex(const QModelIndex &index);
173
174 int modelColumn() const;
175 void setModelColumn(int visibleColumn);
176
177 int currentIndex() const;
178 QString currentText() const;
179 QVariant currentData(int role = Qt::UserRole) const;
180
181 QString itemText(int index) const;
182 QIcon itemIcon(int index) const;
183 QVariant itemData(int index, int role = Qt::UserRole) const;
184
185 inline void addItem(const QString &text, const QVariant &userData = QVariant());
186 inline void addItem(const QIcon &icon, const QString &text,
187 const QVariant &userData = QVariant());
188 inline void addItems(const QStringList &texts)
189 { insertItems(count(), texts); }
190
191 inline void insertItem(int index, const QString &text, const QVariant &userData = QVariant());
192 void insertItem(int index, const QIcon &icon, const QString &text,
193 const QVariant &userData = QVariant());
194 void insertItems(int index, const QStringList &texts);
195 void insertSeparator(int index);
196
197 void removeItem(int index);
198
199 void setItemText(int index, const QString &text);
200 void setItemIcon(int index, const QIcon &icon);
201 void setItemData(int index, const QVariant &value, int role = Qt::UserRole);
202
203 QAbstractItemView *view() const;
204 void setView(QAbstractItemView *itemView);
205
206 QSize sizeHint() const override;
207 QSize minimumSizeHint() const override;
208
209 virtual void showPopup();
210 virtual void hidePopup();
211
212 bool event(QEvent *event) override;
213 QVariant inputMethodQuery(Qt::InputMethodQuery) const override;
214 Q_INVOKABLE QVariant inputMethodQuery(Qt::InputMethodQuery query, const QVariant &argument) const;
215
216public Q_SLOTS:
217 void clear();
218 void clearEditText();
219 void setEditText(const QString &text);
220 void setCurrentIndex(int index);
221 void setCurrentText(const QString &text);
222
223Q_SIGNALS:
224 void editTextChanged(const QString &);
225 void activated(int index);
226 void textActivated(const QString &);
227 void highlighted(int index);
228 void textHighlighted(const QString &);
229 void currentIndexChanged(int index);
230 void currentIndexChanged(const QString &);
231 void currentTextChanged(const QString &);
232#if QT_DEPRECATED_SINCE(5, 15)
233 QT_DEPRECATED_VERSION_X(5, 15, "Use textActivated() instead")
234 void activated(const QString &);
235 QT_DEPRECATED_VERSION_X(5, 15, "Use textHighlighted() instead")
236 void highlighted(const QString &);
237#endif
238
239protected:
240 void focusInEvent(QFocusEvent *e) override;
241 void focusOutEvent(QFocusEvent *e) override;
242 void changeEvent(QEvent *e) override;
243 void resizeEvent(QResizeEvent *e) override;
244 void paintEvent(QPaintEvent *e) override;
245 void showEvent(QShowEvent *e) override;
246 void hideEvent(QHideEvent *e) override;
247 void mousePressEvent(QMouseEvent *e) override;
248 void mouseReleaseEvent(QMouseEvent *e) override;
249 void keyPressEvent(QKeyEvent *e) override;
250 void keyReleaseEvent(QKeyEvent *e) override;
251#if QT_CONFIG(wheelevent)
252 void wheelEvent(QWheelEvent *e) override;
253#endif
254#ifndef QT_NO_CONTEXTMENU
255 void contextMenuEvent(QContextMenuEvent *e) override;
256#endif // QT_NO_CONTEXTMENU
257 void inputMethodEvent(QInputMethodEvent *) override;
258 void initStyleOption(QStyleOptionComboBox *option) const;
259
260
261protected:
262 QComboBox(QComboBoxPrivate &, QWidget *);
263
264private:
265 Q_DECLARE_PRIVATE(QComboBox)
266 Q_DISABLE_COPY(QComboBox)
267 Q_PRIVATE_SLOT(d_func(), void _q_itemSelected(const QModelIndex &item))
268 Q_PRIVATE_SLOT(d_func(), void _q_emitHighlighted(const QModelIndex &))
269 Q_PRIVATE_SLOT(d_func(), void _q_emitCurrentIndexChanged(const QModelIndex &index))
270 Q_PRIVATE_SLOT(d_func(), void _q_editingFinished())
271 Q_PRIVATE_SLOT(d_func(), void _q_returnPressed())
272 Q_PRIVATE_SLOT(d_func(), void _q_resetButton())
273 Q_PRIVATE_SLOT(d_func(), void _q_dataChanged(const QModelIndex &, const QModelIndex &))
274 Q_PRIVATE_SLOT(d_func(), void _q_updateIndexBeforeChange())
275 Q_PRIVATE_SLOT(d_func(), void _q_rowsInserted(const QModelIndex & parent, int start, int end))
276 Q_PRIVATE_SLOT(d_func(), void _q_rowsRemoved(const QModelIndex & parent, int start, int end))
277 Q_PRIVATE_SLOT(d_func(), void _q_modelDestroyed())
278 Q_PRIVATE_SLOT(d_func(), void _q_modelReset())
279#if QT_CONFIG(completer)
280 Q_PRIVATE_SLOT(d_func(), void _q_completerActivated(const QModelIndex &index))
281#endif
282};
283
284inline void QComboBox::addItem(const QString &atext, const QVariant &auserData)
285{ insertItem(count(), atext, auserData); }
286inline void QComboBox::addItem(const QIcon &aicon, const QString &atext,
287 const QVariant &auserData)
288{ insertItem(count(), aicon, atext, auserData); }
289
290inline void QComboBox::insertItem(int aindex, const QString &atext,
291 const QVariant &auserData)
292{ insertItem(aindex, QIcon(), atext, auserData); }
293
294QT_END_NAMESPACE
295
296#endif // QCOMBOBOX_H
297