1/*
2 This file is part of the KDE libraries
3
4 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org>
5 SPDX-FileCopyrightText: 2000 Stefan Schimanski <1Stein@gmx.de>
6 SPDX-FileCopyrightText: 2000, 2001, 2002, 2003, 2004 Dawit Alemayehu <adawit@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCOMPLETIONBOX_H
12#define KCOMPLETIONBOX_H
13
14#include "kcompletion_export.h"
15#include <QListWidget>
16#include <memory>
17
18class KCompletionBoxPrivate;
19class QEvent;
20
21/*!
22 * \class KCompletionBox
23 * \inmodule KCompletion
24 *
25 * \brief A helper widget for "completion-widgets" (KLineEdit, KComboBox)).
26 *
27 * A little utility class for "completion-widgets", like KLineEdit or
28 * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without
29 * any window decoration, usually directly under the lineedit or combobox.
30 * It is filled with all possible matches for a completion, so the user
31 * can select the one he wants.
32 *
33 * It is used when KCompletion::CompletionMode == CompletionPopup or CompletionPopupAuto.
34 */
35class KCOMPLETION_EXPORT KCompletionBox : public QListWidget
36{
37 Q_OBJECT
38
39 /*!
40 * \property KCompletionBox::isTabHandling
41 */
42 Q_PROPERTY(bool isTabHandling READ isTabHandling WRITE setTabHandling)
43
44 /*!
45 * \property KCompletionBox::cancelledText
46 */
47 Q_PROPERTY(QString cancelledText READ cancelledText WRITE setCancelledText)
48
49 /*!
50 * \property KCompletionBox::activateOnSelect
51 */
52 Q_PROPERTY(bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect)
53
54public:
55 /*!
56 * Constructs a KCompletionBox.
57 *
58 * The \a parent widget is used to give the focus back when pressing the
59 * up-button on the very first item.
60 */
61 explicit KCompletionBox(QWidget *parent = nullptr);
62
63 ~KCompletionBox() override;
64
65 QSize sizeHint() const override;
66
67 /*!
68 * Returns \c true if selecting an item results in the emission of the selected() signal.
69 */
70 bool activateOnSelect() const;
71
72 /*!
73 * Returns a list of all items currently in the box.
74 */
75 QStringList items() const;
76
77 /*!
78 * Returns \c true if this widget is handling Tab-key events to traverse the
79 * items in the dropdown list, otherwise false.
80 *
81 * Default is \c true.
82 *
83 * \sa setTabHandling
84 */
85 bool isTabHandling() const;
86
87 /*!
88 * Returns the text set via setCancelledText() or QString().
89 */
90 QString cancelledText() const;
91
92public Q_SLOTS:
93 /*!
94 * Inserts \a items into the box. Does not clear the items before.
95 * \a index determines at which position \a items will be inserted.
96 * (defaults to appending them at the end)
97 */
98 void insertItems(const QStringList &items, int index = -1);
99
100 /*!
101 * Clears the box and inserts \a items.
102 */
103 void setItems(const QStringList &items);
104
105 /*!
106 * Adjusts the size of the box to fit the width of the parent given in the
107 * constructor and pops it up at the most appropriate place, relative to
108 * the parent.
109 *
110 * Depending on the screensize and the position of the parent, this may
111 * be a different place, however the default is to pop it up and the
112 * lower left corner of the parent.
113 *
114 * Make sure to hide() the box when appropriate.
115 */
116 virtual void popup();
117
118 /*!
119 * Makes this widget (when visible) capture Tab-key events to traverse the
120 * items in the dropdown list (Tab goes down, Shift+Tab goes up).
121 *
122 * On by default, but should be turned off when used in combination with KUrlCompletion.
123 * When off, KLineEdit handles Tab itself, making it select the current item from the completion box,
124 * which is particularly useful when using KUrlCompletion.
125 *
126 * \sa isTabHandling
127 */
128 void setTabHandling(bool enable);
129
130 /*!
131 * Sets the text to be emitted if the user chooses not to
132 * pick from the available matches.
133 *
134 * If the cancelled text is not set through this function, the
135 * userCancelled signal will not be emitted.
136 *
137 * \a text the text to be emitted if the user cancels this box
138 *
139 * \sa userCancelled( const QString& )
140 */
141 void setCancelledText(const QString &text);
142
143 /*!
144 * Set whether or not the selected signal should be emitted when an
145 * item is selected. By default the selected() signal is emitted.
146 *
147 * \a doEmit false if the signal should not be emitted.
148 */
149 void setActivateOnSelect(bool doEmit);
150
151 /*!
152 * Moves the selection one line down or select the first item if nothing is selected yet.
153 */
154 void down();
155
156 /*!
157 * Moves the selection one line up or select the first item if nothing is selected yet.
158 */
159 void up();
160
161 /*!
162 * Moves the selection one page down.
163 */
164 void pageDown();
165
166 /*!
167 * Moves the selection one page up.
168 */
169 void pageUp();
170
171 /*!
172 * Moves the selection up to the first item.
173 */
174 void home();
175
176 /*!
177 * Moves the selection down to the last item.
178 */
179 void end();
180
181 /*!
182 * Reimplemented for internal reasons. API is unaffected.
183 * Call it only if you really need it (i.e. the widget was hidden before) to have better performance.
184 */
185 void setVisible(bool visible) override;
186
187Q_SIGNALS:
188 /*!
189 * Emitted when an item is selected, \a text is the text of the selected item.
190 *
191 * \since 5.81
192 */
193 void textActivated(const QString &text);
194
195 /*!
196 * Emitted whenever the user chooses to ignore the available
197 * selections and closes this box.
198 */
199 void userCancelled(const QString &);
200
201protected:
202 /*!
203 * This calculates the size of the dropdown and the relative position of the top
204 * left corner with respect to the parent widget. This matches the geometry and position
205 * normally used by K/QComboBox when used with one.
206 */
207 QRect calculateGeometry() const;
208
209 /*!
210 * This properly resizes and repositions the listbox.
211 *
212 * \since 5.0
213 */
214 void resizeAndReposition();
215
216 /*
217 * Reimplemented from QListWidget to get events from the viewport (to hide
218 * this widget on mouse-click, Escape-presses, etc.
219 */
220 bool eventFilter(QObject *, QEvent *) override;
221
222 /*!
223 * The preferred global coordinate at which the completion box's top left corner
224 * should be positioned.
225 */
226 virtual QPoint globalPositionHint() const;
227
228protected Q_SLOTS:
229 /*!
230 * Called when an item is activated. Emits KCompletionBox::textActivated(const QString &) with the item text.
231 *
232 * \note For releases <= 5.81, this slot emitted KCompletionBox::activated(const QString &) with the item text.
233 */
234 virtual void slotActivated(QListWidgetItem *);
235
236private:
237 std::unique_ptr<KCompletionBoxPrivate> const d;
238};
239
240#endif // KCOMPLETIONBOX_H
241

source code of kcompletion/src/kcompletionbox.h