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 | |
27 | class 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 | */ |
48 | class KDEUI_EXPORT KHistoryComboBox : public KComboBox |
49 | { |
50 | Q_OBJECT |
51 | Q_PROPERTY( QStringList historyItems READ historyItems WRITE setHistoryItems ) |
52 | |
53 | public: |
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 | |
186 | public 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 | |
213 | Q_SIGNALS: |
214 | /** |
215 | * Emitted when the history was cleared by the entry in the popup menu. |
216 | */ |
217 | void cleared(); |
218 | |
219 | protected: |
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 | |
245 | private 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 ( QMenu* ); |
261 | |
262 | /** |
263 | * Used to emit the activated(QString) signal when enter is pressed |
264 | */ |
265 | void slotSimulateActivated( const QString& ); |
266 | |
267 | private: |
268 | void init( bool useCompletion ); |
269 | void rotateUp(); |
270 | void rotateDown(); |
271 | |
272 | private: |
273 | class Private; |
274 | friend class Private; |
275 | Private* const d; |
276 | |
277 | Q_DISABLE_COPY(KHistoryComboBox) |
278 | }; |
279 | |
280 | |
281 | #endif |
282 | |
283 | |