KCompletion

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

KDE's Doxygen guidelines are available online.