KCompletion

khistorycombobox.h
1 /*
2  This file is part of the KDE libraries
3 
4  SPDX-FileCopyrightText: 2000, 2001 Dawit Alemayehu <[email protected]>
5  SPDX-FileCopyrightText: 2000, 2001 Carsten Pfeiffer <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.1-or-later
8 */
9 
10 #ifndef KHistoryComboBoxBOX_H
11 #define KHistoryComboBoxBOX_H
12 
13 #include <kcombobox.h>
14 #include <kcompletion_export.h>
15 
16 #include <functional>
17 
18 class KPixmapProvider;
19 class KHistoryComboBoxPrivate;
20 
21 /**
22  * @class KHistoryComboBox khistorycombobox.h KHistoryComboBox
23  *
24  * @short A combobox for offering a history and completion
25  *
26  * A combobox which implements a history like a unix shell. You can navigate
27  * through all the items by using the Up or Down arrows (configurable of
28  * course). Additionally, weighted completion is available. So you should
29  * load and save the completion list to preserve the weighting between
30  * sessions.
31  *
32  * KHistoryComboBox obeys the HISTCONTROL environment variable to determine
33  * whether duplicates in the history should be tolerated in
34  * addToHistory() or not. During construction of KHistoryComboBox,
35  * duplicates will be disabled when HISTCONTROL is set to "ignoredups" or
36  * "ignoreboth". Otherwise, duplicates are enabled by default.
37  *
38  * \image html khistorycombobox.png "KHistoryComboBox widget"
39  *
40  * @author Carsten Pfeiffer <[email protected]>
41  */
42 class KCOMPLETION_EXPORT KHistoryComboBox : public KComboBox
43 {
44  Q_OBJECT
45 
46  Q_PROPERTY(QStringList historyItems READ historyItems WRITE setHistoryItems)
47 
48 public:
49  /**
50  * Constructs a "read-write" combobox. A read-only history combobox
51  * doesn't make much sense, so it is only available as read-write.
52  * Completion will be used automatically for the items in the combo.
53  *
54  * The insertion-policy is set to NoInsert, you have to add the items
55  * yourself via the slot addToHistory. If you want every item added,
56  * use
57  *
58  * \code
59  * connect( combo, SIGNAL( activated( const QString& )),
60  * combo, SLOT( addToHistory( const QString& )));
61  * \endcode
62  *
63  * Use QComboBox::setMaxCount() to limit the history.
64  *
65  * @p parent the parent object of this widget.
66  */
67  explicit KHistoryComboBox(QWidget *parent = nullptr);
68 
69  /**
70  * Same as the previous constructor, but additionally has the option
71  * to specify whether you want to let KHistoryComboBox handle completion
72  * or not. If set to @c true, KHistoryComboBox will sync the completion to the
73  * contents of the combobox.
74  */
75  explicit KHistoryComboBox(bool useCompletion, QWidget *parent = nullptr);
76 
77  /**
78  * Destructs the combo, the completion-object and the pixmap-provider
79  */
80  ~KHistoryComboBox() override;
81 
82  /**
83  * Inserts @p items into the combobox. @p items might get
84  * truncated if it is longer than maxCount()
85  *
86  * @see historyItems
87  */
88  void setHistoryItems(const QStringList &items);
89 
90  /**
91  * Inserts @p items into the combobox. @p items might get
92  * truncated if it is longer than maxCount()
93  *
94  * Set @c setCompletionList to true, if you don't have a list of
95  * completions. This tells KHistoryComboBox to use all the items for the
96  * completion object as well.
97  * You won't have the benefit of weighted completion though, so normally
98  * you should do something like
99  * \code
100  * KConfigGroup config(KSharedConfig::openConfig(), "somegroup");
101  *
102  * // load the history and completion list after creating the history combo
103  * QStringList list;
104  * list = config.readEntry("Completion list", QStringList());
105  * combo->completionObject()->setItems(list);
106  * list = config.readEntry("History list", QStringList());
107  * combo->setHistoryItems(list);
108  *
109  * [...]
110  *
111  * // save the history and completion list when the history combo is
112  * // destroyed
113  * QStringList list;
114  * KConfigGroup config(KSharedConfig::openConfig(), "somegroup");
115  * list = combo->completionObject()->items();
116  * config.writeEntry("Completion list", list);
117  * list = combo->historyItems();
118  * config.writeEntry("History list", list);
119  * \endcode
120  *
121  * Be sure to use different names for saving with KConfig if you have more
122  * than one KHistoryComboBox.
123  *
124  * @note When @c setCompletionList is true, the items are inserted into the
125  * KCompletion object with mode KCompletion::Insertion and the mode is set
126  * to KCompletion::Weighted afterwards.
127  *
128  * @see historyItems
129  * @see KComboBox::completionObject
130  * @see KCompletion::setItems
131  * @see KCompletion::items
132  */
133  void setHistoryItems(const QStringList &items, bool setCompletionList);
134 
135  /**
136  * Returns the list of history items. Empty, when this is not a read-write
137  * combobox.
138  *
139  * @see setHistoryItems
140  */
141  QStringList historyItems() const;
142 
143  /**
144  * Removes all items named @p item.
145  *
146  * @return @c true if at least one item was removed.
147  *
148  * @see addToHistory
149  */
150  bool removeFromHistory(const QString &item);
151 
152 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 66)
153  /**
154  * Sets a pixmap provider, so that items in the combobox can have a pixmap.
155  * KPixmapProvider is just an abstract class with the one pure virtual
156  * method KPixmapProvider::pixmapFor(). This method is called whenever
157  * an item is added to the KHistoryComboBoxBox. Implement it to return your
158  * own custom pixmaps, or use the KUrlPixmapProvider from KIO,
159  * which uses KMimeType::pixmapForUrl to resolve icons.
160  *
161  * Set @p provider to nullptr if you want to disable pixmaps. Default no pixmaps.
162  *
163  * @see pixmapProvider
164  * @deprecated since 5.66, use setIconProvider
165  */
166  KCOMPLETION_DEPRECATED_VERSION(5, 66, "Use setIconProvider")
167  void setPixmapProvider(KPixmapProvider *provider);
168 #endif
169 
170 #if KCOMPLETION_ENABLE_DEPRECATED_SINCE(5, 66)
171  /**
172  * @returns the current pixmap provider.
173  * @see setPixmapProvider
174  * @see KPixmapProvider
175  * @deprecated since 5.66, unused
176  */
177  KCOMPLETION_DEPRECATED_VERSION(5, 66, "unused")
178  KPixmapProvider *pixmapProvider() const;
179 #endif
180 
181  /**
182  * Sets an icon provider, so that items in the combobox can have an icon.
183  * The provider is a function that takes a QString and returns a QIcon
184  * @since 5.66
185  */
186  void setIconProvider(std::function<QIcon(const QString &)> providerFunction);
187 
189 
190 public Q_SLOTS:
191  /**
192  * Adds an item to the end of the history list and to the completion list.
193  * If maxCount() is reached, the first item of the list will be
194  * removed.
195  *
196  * If the last inserted item is the same as @p item, it will not be
197  * inserted again.
198  *
199  * If duplicatesEnabled() is false, any equal existing item will be
200  * removed before @p item is added.
201  *
202  * @note By using this method and not the Q and KComboBox insertItem()
203  * methods, you make sure that the combobox stays in sync with the
204  * completion. It would be annoying if completion would give an item
205  * not in the combobox, and vice versa.
206  *
207  * @see removeFromHistory
208  * @see QComboBox::setDuplicatesEnabled
209  */
210  void addToHistory(const QString &item);
211 
212  /**
213  * Clears the history and the completion list.
214  */
215  void clearHistory();
216 
217  /**
218  * Resets the current position of the up/down history. Call this
219  * when you manually call setCurrentItem() or clearEdit().
220  */
221  void reset();
222 
223 Q_SIGNALS:
224  /**
225  * Emitted when the history was cleared by the entry in the popup menu.
226  */
227  void cleared();
228 
229 protected:
230  /**
231  * Handling key-events, the shortcuts to rotate the items.
232  */
233  void keyPressEvent(QKeyEvent *) override;
234 
235  /**
236  * Handling wheel-events, to rotate the items.
237  */
238  void wheelEvent(QWheelEvent *ev) override;
239 
240  /**
241  * Inserts @p items into the combo, honoring pixmapProvider()
242  * Does not update the completionObject.
243  *
244  * @note duplicatesEnabled() is not honored here.
245  *
246  * Called from setHistoryItems() and setPixmapProvider()
247  */
248  void insertItems(const QStringList &items);
249 
250  /**
251  * @returns if we can modify the completion object or not.
252  */
253  bool useCompletion() const;
254 
255 private:
256  Q_DECLARE_PRIVATE_D(KComboBox::d_ptr, KHistoryComboBox)
257 #if KCOMPLETION_BUILD_DEPRECATED_SINCE(5, 79)
258  // Unused, kept for ABI compatibility
259  const void *__kcompletion_d_do_not_use;
260 #endif
261 
263 };
264 
265 #endif
Q_PROPERTY(...)
virtual void keyPressEvent(QKeyEvent *e) override
Q_SLOTSQ_SLOTS
An abstract interface for looking up icons.
void insertItems(int index, const QStringList &list)
virtual void wheelEvent(QWheelEvent *e) override
A combo box with completion support.
Definition: kcombobox.h:135
Q_SIGNALSQ_SIGNALS
A combobox for offering a history and completion.
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:56:56 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.