KCompletion

kcompletionbox.h
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{
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
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
void up()
Moves the selection one line up or select the first item if nothing is selected yet.
virtual void slotActivated(QListWidgetItem *)
Called when an item is activated.
void resizeAndReposition()
This properly resizes and repositions the listbox.
void userCancelled(const QString &)
Emitted whenever the user chooses to ignore the available selections and closes this box.
void textActivated(const QString &text)
Emitted when an item is selected, text is the text of the selected item.
void end()
Moves the selection down to the last item.
void setItems(const QStringList &items)
Clears the box and inserts items.
void home()
Moves the selection up to the first item.
void setCancelledText(const QString &text)
Sets the text to be emitted if the user chooses not to pick from the available matches.
void setActivateOnSelect(bool doEmit)
Set whether or not the selected signal should be emitted when an item is selected.
void pageUp()
Moves the selection one page up.
KCompletionBox(QWidget *parent=nullptr)
Constructs a KCompletionBox.
void down()
Moves the selection one line down or select the first item if nothing is selected yet.
virtual QPoint globalPositionHint() const
The preferred global coordinate at which the completion box's top left corner should be positioned.
QStringList items() const
Returns a list of all items currently in the box.
virtual void popup()
Adjusts the size of the box to fit the width of the parent given in the constructor and pops it up at...
void pageDown()
Moves the selection one page down.
void setTabHandling(bool enable)
Makes this widget (when visible) capture Tab-key events to traverse the items in the dropdown list (T...
QRect calculateGeometry() const
This calculates the size of the dropdown and the relative position of the top left corner with respec...
virtual bool eventFilter(QObject *object, QEvent *event) override
virtual QSize sizeHint() const const override
QListWidget(QWidget *parent)
void insertItems(int row, const QStringList &labels)
QList< QListWidgetItem * > items(const QMimeData *data) const const
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QObject * parent() const const
virtual void setVisible(bool visible)
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 24 2025 11:58:10 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.