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

source code of kcompletion/src/kcompletionbox.h