1/* This file is part of the KDE libraries
2
3 Copyright (c) 2000,2001 Dawit Alemayehu <adawit@kde.org>
4 Copyright (c) 2000,2001 Carsten Pfeiffer <pfeiffer@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License (LGPL) as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KHistoryComboBoxBOX_H
23#define KHistoryComboBoxBOX_H
24
25#include <kcombobox.h>
26
27class KPixmapProvider;
28
29/**
30 * @short A combobox for offering a history and completion
31 *
32 * A combobox which implements a history like a unix shell. You can navigate
33 * through all the items by using the Up or Down arrows (configurable of
34 * course). Additionally, weighted completion is available. So you should
35 * load and save the completion list to preserve the weighting between
36 * sessions.
37 *
38 * KHistoryComboBox obeys the HISTCONTROL environment variable to determine
39 * whether duplicates in the history should be tolerated in
40 * addToHistory() or not. During construction of KHistoryComboBox,
41 * duplicates will be disabled when HISTCONTROL is set to "ignoredups" or
42 * "ignoreboth". Otherwise, duplicates are enabled by default.
43 *
44 * \image html khistorycombobox.png "KDE History Combo Box"
45 *
46 * @author Carsten Pfeiffer <pfeiffer@kde.org>
47 */
48class KDEUI_EXPORT KHistoryComboBox : public KComboBox
49{
50 Q_OBJECT
51 Q_PROPERTY( QStringList historyItems READ historyItems WRITE setHistoryItems )
52
53public:
54 /**
55 * Constructs a "read-write" combobox. A read-only history combobox
56 * doesn't make much sense, so it is only available as read-write.
57 * Completion will be used automatically for the items in the combo.
58 *
59 * The insertion-policy is set to NoInsert, you have to add the items
60 * yourself via the slot addToHistory. If you want every item added,
61 * use
62 *
63 * \code
64 * connect( combo, SIGNAL( activated( const QString& )),
65 * combo, SLOT( addToHistory( const QString& )));
66 * \endcode
67 *
68 * Use QComboBox::setMaxCount() to limit the history.
69 *
70 * @p parent the parent object of this widget.
71 */
72 explicit KHistoryComboBox( QWidget *parent = 0 );
73
74 /**
75 * Same as the previous constructor, but additionally has the option
76 * to specify whether you want to let KHistoryComboBox handle completion
77 * or not. If set to @p true, KHistoryComboBox will sync the completion to the
78 * contents of the combobox.
79 */
80 explicit KHistoryComboBox( bool useCompletion, QWidget *parent = 0 );
81
82 /**
83 * Destructs the combo, the completion-object and the pixmap-provider
84 */
85 ~KHistoryComboBox();
86
87 /**
88 * Inserts @p items into the combobox. @p items might get
89 * truncated if it is longer than maxCount()
90 *
91 * @see historyItems
92 */
93 void setHistoryItems( const QStringList &items );
94
95 /**
96 * Inserts @p items into the combobox. @p items might get
97 * truncated if it is longer than maxCount()
98 *
99 * Set @p setCompletionList to true, if you don't have a list of
100 * completions. This tells KHistoryComboBox to use all the items for the
101 * completion object as well.
102 * You won't have the benefit of weighted completion though, so normally
103 * you should do something like
104 * \code
105 * KConfigGroup config(KGlobal::config(), "somegroup");
106 *
107 * // load the history and completion list after creating the history combo
108 * QStringList list;
109 * list = config.readEntry("Completion list", QStringList());
110 * combo->completionObject()->setItems(list);
111 * list = config.readEntry("History list", QStringList());
112 * combo->setHistoryItems(list);
113 *
114 * [...]
115 *
116 * // save the history and completion list when the history combo is
117 * // destroyed
118 * QStringList list;
119 * KConfigGroup config(KGlobal::config(), "somegroup");
120 * list = combo->completionObject()->items();
121 * config.writeEntry("Completion list", list);
122 * list = combo->historyItems();
123 * config.writeEntry("History list", list);
124 * \endcode
125 *
126 * Be sure to use different names for saving with KConfig if you have more
127 * than one KHistoryComboBox.
128 *
129 * Note: When @p setCompletionList is true, the items are inserted into the
130 * KCompletion object with mode KCompletion::Insertion and the mode is set
131 * to KCompletion::Weighted afterwards.
132 *
133 * @see historyItems
134 * @see KComboBox::completionObject
135 * @see KCompletion::setItems
136 * @see KCompletion::items
137 */
138 void setHistoryItems( const QStringList &items, bool setCompletionList );
139
140 /**
141 * Returns the list of history items. Empty, when this is not a read-write
142 * combobox.
143 *
144 * @see setHistoryItems
145 */
146 QStringList historyItems() const;
147
148 /**
149 * Removes all items named @p item.
150 *
151 * @return @p true if at least one item was removed.
152 *
153 * @see addToHistory
154 */
155 bool removeFromHistory( const QString& item );
156
157 /**
158 * Sets a pixmap provider, so that items in the combobox can have a pixmap.
159 * KPixmapProvider is just an abstract class with the one pure virtual
160 * method KPixmapProvider::pixmapFor(). This method is called whenever
161 * an item is added to the KHistoryComboBoxBox. Implement it to return your
162 * own custom pixmaps, or use the KUrlPixmapProvider from libkio,
163 * which uses KMimeType::pixmapForUrl to resolve icons.
164 *
165 * Set @p prov to 0L if you want to disable pixmaps. Default no pixmaps.
166 *
167 * @see pixmapProvider
168 */
169 void setPixmapProvider( KPixmapProvider *prov );
170
171 /**
172 * @returns the current pixmap provider.
173 * @see setPixmapProvider
174 * @see KPixmapProvider
175 */
176 KPixmapProvider * pixmapProvider() const;
177
178 /**
179 * Resets the current position of the up/down history. Call this
180 * when you manually call setCurrentItem() or clearEdit().
181 */
182 void reset();
183
184 using QComboBox::insertItems;
185
186public Q_SLOTS:
187 /**
188 * Adds an item to the end of the history list and to the completion list.
189 * If maxCount() is reached, the first item of the list will be
190 * removed.
191 *
192 * If the last inserted item is the same as @p item, it will not be
193 * inserted again.
194 *
195 * If duplicatesEnabled() is false, any equal existing item will be
196 * removed before @p item is added.
197 *
198 * Note: By using this method and not the Q and KComboBox insertItem()
199 * methods, you make sure that the combobox stays in sync with the
200 * completion. It would be annoying if completion would give an item
201 * not in the combobox, and vice versa.
202 *
203 * @see removeFromHistory
204 * @see QComboBox::setDuplicatesEnabled
205 */
206 void addToHistory( const QString& item );
207
208 /**
209 * Clears the history and the completion list.
210 */
211 void clearHistory();
212
213Q_SIGNALS:
214 /**
215 * Emitted when the history was cleared by the entry in the popup menu.
216 */
217 void cleared();
218
219protected:
220 /**
221 * Handling key-events, the shortcuts to rotate the items.
222 */
223 virtual void keyPressEvent( QKeyEvent * );
224
225 /**
226 * Handling wheel-events, to rotate the items.
227 */
228 virtual void wheelEvent( QWheelEvent *ev );
229
230 /**
231 * Inserts @p items into the combo, honoring pixmapProvider()
232 * Does not update the completionObject.
233 *
234 * Note: duplicatesEnabled() is not honored here.
235 *
236 * Called from setHistoryItems() and setPixmapProvider()
237 */
238 void insertItems( const QStringList& items );
239
240 /**
241 * @returns if we can modify the completion object or not.
242 */
243 bool useCompletion() const;
244
245private Q_SLOTS:
246 /**
247 * Resets the iterate index to -1
248 */
249 void slotReset();
250
251 /**
252 * Called from the popupmenu,
253 * calls clearHistory() and emits cleared()
254 */
255 void slotClear();
256
257 /**
258 * Appends our own context menu entry.
259 */
260 void addContextMenuItems( QMenu* );
261
262 /**
263 * Used to emit the activated(QString) signal when enter is pressed
264 */
265 void slotSimulateActivated( const QString& );
266
267private:
268 void init( bool useCompletion );
269 void rotateUp();
270 void rotateDown();
271
272private:
273 class Private;
274 friend class Private;
275 Private* const d;
276
277 Q_DISABLE_COPY(KHistoryComboBox)
278};
279
280
281#endif
282
283