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

source code of kcompletion/src/khistorycombobox.h