1
by Jonathan Riddell
Import upstream version 3.4.0 |
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
|
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
18 |
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
19 |
Boston, MA 02110-1301, USA.
|
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
20 |
*/
|
21 |
||
22 |
#ifndef _KCOMBOBOX_H
|
|
23 |
#define _KCOMBOBOX_H
|
|
24 |
||
25 |
#include <qlineedit.h> |
|
26 |
#include <qcombobox.h> |
|
27 |
||
28 |
#include <kcompletion.h> |
|
29 |
||
30 |
class QListBoxItem; |
|
31 |
class QPopupMenu; |
|
32 |
class QLineEdit; |
|
33 |
||
34 |
class KCompletionBox; |
|
35 |
class KURL; |
|
36 |
||
37 |
/**
|
|
38 |
* @short An enhanced combo box.
|
|
39 |
*
|
|
40 |
* A combined button, line-edit and a popup list widget.
|
|
41 |
*
|
|
42 |
* \b Detail \n
|
|
43 |
*
|
|
44 |
* This widget inherits from QComboBox and implements the following
|
|
45 |
* additional functionalities: a completion object that provides both automatic
|
|
46 |
* and manual text completion as well as text rotation features, configurable
|
|
47 |
* key-bindings to activate these features, and a popup-menu item that can be
|
|
48 |
* used to allow the user to change the text completion mode on the fly.
|
|
49 |
*
|
|
50 |
* To support these new features KComboBox emits a few additional signals
|
|
51 |
* such as completion( const QString& ) and textRotation( KeyBindgingType ).
|
|
52 |
* The completion signal can be connected to a slot that will assist the user in
|
|
53 |
* filling out the remaining text while the rotation signal can be used to traverse
|
|
54 |
* through all possible matches whenever text completion results in multiple matches.
|
|
55 |
* Additionally, a returnPressed() and a returnPressed( const QString& )
|
|
56 |
* signals are emitted when the user presses the Enter/Return key.
|
|
57 |
*
|
|
58 |
* KCombobox by default creates a completion object when you invoke the
|
|
59 |
* completionObject( bool ) member function for the first time or
|
|
60 |
* explicitly use setCompletionObject( KCompletion*, bool ) to assign your
|
|
61 |
* own completion object. Additionally, to make this widget more functional,
|
|
62 |
* KComboBox will by default handle text rotation and completion events
|
|
63 |
* internally whenever a completion object is created through either one of the
|
|
64 |
* methods mentioned above. If you do not need this functionality, simply use
|
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
65 |
* @p setHandleSignals(bool) or alternatively set the boolean parameter in the
|
66 |
* @p setCompletionObject call to false.
|
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
67 |
*
|
68 |
* Beware: The completion object can be deleted on you, especially if a call
|
|
69 |
* such as setEditable(false) is made. Store the pointer at your own risk,
|
|
70 |
* and consider using QGuardedPtr<KCompletion>.
|
|
71 |
*
|
|
72 |
* The default key-bindings for completion and rotation is determined from the
|
|
73 |
* global settings in KStdAccel. These values, however, can be overridden
|
|
74 |
* locally by invoking KCompletionBase::setKeyBinding(). The values can
|
|
75 |
* easily be reverted back to the default setting, by simply calling
|
|
76 |
* useGlobalSettings(). An alternate method would be to default individual
|
|
77 |
* key-bindings by usning setKeyBinding() with the default second argument.
|
|
78 |
*
|
|
79 |
* A non-editable combobox only has one completion mode, @p CompletionAuto.
|
|
80 |
* Unlike an editable combobox the CompletionAuto mode, works by matching
|
|
81 |
* any typed key with the first letter of entries in the combobox. Please note
|
|
82 |
* that if you call setEditable( false ) to change an editable combobox to a
|
|
83 |
* non-editable one, the text completion object associated with the combobox will
|
|
84 |
* no longer exist unless you created the completion object yourself and assigned
|
|
85 |
* it to this widget or you called setAutoDeleteCompletionObject( false ). In other
|
|
86 |
* words do not do the following:
|
|
87 |
*
|
|
88 |
* \code
|
|
89 |
* KComboBox* combo = new KCompletionBox(true, this, "mywidget");
|
|
90 |
* KCompletion* comp = combo->completionObject();
|
|
91 |
* combo->setEditable( false );
|
|
92 |
* comp->clear(); // CRASH: completion object does not exist anymore.
|
|
93 |
* \endcode
|
|
94 |
*
|
|
95 |
*
|
|
96 |
* A read-only KComboBox will have the same background color as a
|
|
97 |
* disabled KComboBox, but its foreground color will be the one used for
|
|
98 |
* the read-write mode. This differs from QComboBox's implementation
|
|
99 |
* and is done to give visual distinction between the three different modes:
|
|
100 |
* disabled, read-only, and read-write.
|
|
101 |
*
|
|
102 |
* \b Usage \n
|
|
103 |
*
|
|
104 |
* To enable the basic completion feature:
|
|
105 |
*
|
|
106 |
* \code
|
|
107 |
* KComboBox *combo = new KComboBox( true, this, "mywidget" );
|
|
108 |
* KCompletion *comp = combo->completionObject();
|
|
109 |
* // Connect to the return pressed signal - optional
|
|
110 |
* connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
|
|
111 |
*
|
|
112 |
* // Provide the to be completed strings. Note that those are separate from the combo's
|
|
113 |
* // contents.
|
|
114 |
* comp->insertItems( someQStringList );
|
|
115 |
* \endcode
|
|
116 |
*
|
|
117 |
* To use your own completion object:
|
|
118 |
*
|
|
119 |
* \code
|
|
120 |
* KComboBox *combo = new KComboBox( this,"mywidget" );
|
|
121 |
* KURLCompletion *comp = new KURLCompletion();
|
|
122 |
* combo->setCompletionObject( comp );
|
|
123 |
* // Connect to the return pressed signal - optional
|
|
124 |
* connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
|
|
125 |
* \endcode
|
|
126 |
*
|
|
127 |
* Note that you have to either delete the allocated completion object
|
|
128 |
* when you don't need it anymore, or call
|
|
129 |
* setAutoDeleteCompletionObject( true );
|
|
130 |
*
|
|
131 |
* Miscellaneous function calls:
|
|
132 |
*
|
|
133 |
* \code
|
|
134 |
* // Tell the widget not to handle completion and rotation
|
|
135 |
* combo->setHandleSignals( false );
|
|
136 |
* // Set your own completion key for manual completions.
|
|
137 |
* combo->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
|
|
138 |
* // Hide the context (popup) menu
|
|
139 |
* combo->setContextMenuEnabled( false );
|
|
140 |
* \endcode
|
|
141 |
*
|
|
142 |
* @author Dawit Alemayehu <adawit@kde.org>
|
|
143 |
*/
|
|
144 |
class KDEUI_EXPORT KComboBox : public QComboBox, public KCompletionBase |
|
145 |
{
|
|
146 |
Q_OBJECT
|
|
147 |
Q_PROPERTY( bool autoCompletion READ autoCompletion WRITE setAutoCompletion ) |
|
148 |
Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled ) |
|
149 |
Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled ) |
|
150 |
Q_PROPERTY( bool trapReturnKey READ trapReturnKey WRITE setTrapReturnKey ) |
|
151 |
||
152 |
public: |
|
153 |
||
154 |
/**
|
|
155 |
* Constructs a read-only or rather select-only combo box with a
|
|
156 |
* parent object and a name.
|
|
157 |
*
|
|
158 |
* @param parent The parent object of this widget
|
|
159 |
* @param name The name of this widget
|
|
160 |
*/
|
|
161 |
KComboBox( QWidget *parent=0, const char *name=0 ); |
|
162 |
||
163 |
/**
|
|
164 |
* Constructs a "read-write" or "read-only" combo box depending on
|
|
165 |
* the value of the first argument( @p rw ) with a parent, a
|
|
166 |
* name.
|
|
167 |
*
|
|
168 |
* @param rw When @p true, widget will be editable.
|
|
169 |
* @param parent The parent object of this widget.
|
|
170 |
* @param name The name of this widget.
|
|
171 |
*/
|
|
172 |
KComboBox( bool rw, QWidget *parent=0, const char *name=0 ); |
|
173 |
||
174 |
/**
|
|
175 |
* Destructor.
|
|
176 |
*/
|
|
177 |
virtual ~KComboBox(); |
|
178 |
||
179 |
/**
|
|
180 |
* Sets @p url into the edit field of the combobox. It uses
|
|
181 |
* KURL::prettyURL() so that the url is properly decoded for
|
|
182 |
* displaying.
|
|
183 |
*/
|
|
184 |
void setEditURL( const KURL& url ); |
|
185 |
||
186 |
/**
|
|
187 |
* Inserts @p url at position @p index into the combobox. The item will
|
|
188 |
* be appended if @p index is negative. KURL::prettyURL() is used
|
|
189 |
* so that the url is properly decoded for displaying.
|
|
190 |
*/
|
|
191 |
void insertURL( const KURL& url, int index = -1 ); |
|
192 |
||
193 |
/**
|
|
194 |
* Inserts @p url with the pixmap &p pixmap at position @p index into
|
|
195 |
* the combobox. The item will be appended if @p index is negative.
|
|
196 |
* KURL::prettyURL() is used so that the url is properly decoded
|
|
197 |
* for displaying.
|
|
198 |
*/
|
|
199 |
void insertURL( const QPixmap& pixmap, const KURL& url, int index = -1 ); |
|
200 |
||
201 |
/**
|
|
202 |
* Replaces the item at position @p index with @p url.
|
|
203 |
* KURL::prettyURL() is used so that the url is properly decoded
|
|
204 |
* for displaying.
|
|
205 |
*/
|
|
206 |
void changeURL( const KURL& url, int index ); |
|
207 |
||
208 |
/**
|
|
209 |
* Replaces the item at position @p index with @p url and pixmap @p pixmap.
|
|
210 |
* KURL::prettyURL() is used so that the url is properly decoded
|
|
211 |
* for displaying.
|
|
212 |
*/
|
|
213 |
void changeURL( const QPixmap& pixmap, const KURL& url, int index ); |
|
214 |
||
215 |
/**
|
|
216 |
* Returns the current cursor position.
|
|
217 |
*
|
|
218 |
* This method always returns a -1 if the combo-box is @em not
|
|
219 |
* editable (read-write).
|
|
220 |
*
|
|
221 |
* @return Current cursor position.
|
|
222 |
*/
|
|
223 |
int cursorPosition() const { return ( lineEdit() ) ? lineEdit()->cursorPosition() : -1; } |
|
224 |
||
225 |
/**
|
|
226 |
* Re-implemented from QComboBox.
|
|
227 |
*
|
|
228 |
* If @p true, the completion mode will be set to automatic.
|
|
229 |
* Otherwise, it is defaulted to the global setting. This
|
|
230 |
* method has been replaced by the more comprehensive
|
|
231 |
* setCompletionMode().
|
|
232 |
*
|
|
233 |
* @param autocomplete Flag to enable/disable automatic completion mode.
|
|
234 |
*/
|
|
235 |
virtual void setAutoCompletion( bool autocomplete ); |
|
236 |
||
237 |
/**
|
|
238 |
* Re-implemented from QComboBox.
|
|
239 |
*
|
|
240 |
* Returns @p true if the current completion mode is set
|
|
241 |
* to automatic. See its more comprehensive replacement
|
|
242 |
* completionMode().
|
|
243 |
*
|
|
244 |
* @return @p true when completion mode is automatic.
|
|
245 |
*/
|
|
246 |
bool autoCompletion() const { |
|
247 |
return completionMode() == KGlobalSettings::CompletionAuto; |
|
248 |
}
|
|
249 |
||
250 |
/**
|
|
251 |
* Enables or disable the popup (context) menu.
|
|
252 |
*
|
|
253 |
* This method only works if this widget is editable, i.e.
|
|
254 |
* read-write and allows you to enable/disable the context
|
|
255 |
* menu. It does nothing if invoked for a none-editable
|
|
256 |
* combo-box. Note that by default the mode changer item
|
|
257 |
* is made visiable whenever the context menu is enabled.
|
|
258 |
* Use hideModechanger() if you want to hide this
|
|
259 |
* item. Also by default, the context menu is created if
|
|
260 |
* this widget is editable. Call this function with the
|
|
261 |
* argument set to false to disable the popup menu.
|
|
262 |
*
|
|
263 |
* @param showMenu If @p true, show the context menu.
|
|
264 |
*/
|
|
265 |
virtual void setContextMenuEnabled( bool showMenu ); |
|
266 |
||
267 |
/**
|
|
268 |
* Returns @p true when the context menu is enabled.
|
|
269 |
*/
|
|
270 |
bool isContextMenuEnabled() const { return m_bEnableMenu; } |
|
271 |
||
272 |
/**
|
|
273 |
* Enables/Disables handling of URL drops. If enabled and the user
|
|
274 |
* drops an URL, the decoded URL will be inserted. Otherwise the default
|
|
275 |
* behavior of QComboBox is used, which inserts the encoded URL.
|
|
276 |
*
|
|
277 |
* @param enable If @p true, insert decoded URLs
|
|
278 |
*/
|
|
279 |
void setURLDropsEnabled( bool enable ); |
|
280 |
||
281 |
/**
|
|
282 |
* Returns @p true when decoded URL drops are enabled
|
|
283 |
*/
|
|
284 |
bool isURLDropsEnabled() const; |
|
285 |
||
286 |
/**
|
|
287 |
* Convenience method which iterates over all items and checks if
|
|
288 |
* any of them is equal to @p text.
|
|
289 |
*
|
|
290 |
* If @p text is an empty string, @p false
|
|
291 |
* is returned.
|
|
292 |
*
|
|
293 |
* @return @p true if an item with the string @p text is in the combobox.
|
|
294 |
*/
|
|
295 |
bool contains( const QString& text ) const; |
|
296 |
||
297 |
/**
|
|
298 |
* By default, KComboBox recognizes Key_Return and Key_Enter
|
|
299 |
* and emits the returnPressed() signals, but it also lets the
|
|
300 |
* event pass, for example causing a dialog's default-button to
|
|
301 |
* be called.
|
|
302 |
*
|
|
303 |
* Call this method with @p trap equal to true to make KComboBox
|
|
304 |
* stop these events. The signals will still be emitted of course.
|
|
305 |
*
|
|
306 |
* Only affects read-writable comboboxes.
|
|
307 |
*
|
|
308 |
* @see setTrapReturnKey()
|
|
309 |
*/
|
|
310 |
void setTrapReturnKey( bool trap ); |
|
311 |
||
312 |
/**
|
|
313 |
* @return @p true if keyevents of Key_Return or Key_Enter will
|
|
314 |
* be stopped or if they will be propagated.
|
|
315 |
*
|
|
316 |
* @see setTrapReturnKey ()
|
|
317 |
*/
|
|
318 |
bool trapReturnKey() const; |
|
319 |
||
320 |
/**
|
|
321 |
* Re-implemented for internal reasons. API not affected.
|
|
322 |
*/
|
|
323 |
virtual bool eventFilter( QObject *, QEvent * ); |
|
324 |
||
325 |
/**
|
|
326 |
* @returns the completion-box, that is used in completion mode
|
|
327 |
* KGlobalSettings::CompletionPopup and KGlobalSettings::CompletionPopupAuto.
|
|
328 |
* This method will create a completion-box by calling
|
|
329 |
* KLineEdit::completionBox, if none is there, yet.
|
|
330 |
*
|
|
331 |
* @param create Set this to false if you don't want the box to be created
|
|
332 |
* i.e. to test if it is available.
|
|
333 |
*/
|
|
334 |
KCompletionBox * completionBox( bool create = true ); |
|
335 |
||
336 |
/**
|
|
337 |
* Re-implemented for internal reasons. API remains unaffected.
|
|
338 |
* NOTE: Only editable comboboxes can have a line editor. As such
|
|
339 |
* any attempt to assign a line-edit to a non-editable combobox will
|
|
340 |
* simply be ignored.
|
|
341 |
*/
|
|
342 |
virtual void setLineEdit( QLineEdit * ); |
|
343 |
||
344 |
signals: |
|
345 |
/**
|
|
346 |
* Emitted when the user presses the Enter key.
|
|
347 |
*
|
|
348 |
* Note that this signal is only emitted when the widget is editable.
|
|
349 |
*/
|
|
350 |
void returnPressed(); |
|
351 |
||
352 |
/**
|
|
353 |
* Emitted when the user presses the Enter key.
|
|
354 |
*
|
|
355 |
* The argument is the current text being edited. This signal is just like
|
|
356 |
* returnPressed() except it contains the current text as its argument.
|
|
357 |
*
|
|
358 |
* Note that this signal is only emitted when the
|
|
359 |
* widget is editable.
|
|
360 |
*/
|
|
361 |
void returnPressed( const QString& ); |
|
362 |
||
363 |
/**
|
|
364 |
* Emitted when the completion key is pressed.
|
|
365 |
*
|
|
366 |
* The argument is the current text being edited.
|
|
367 |
*
|
|
368 |
* Note that this signal is @em not available when the widget is non-editable
|
|
369 |
* or the completion mode is set to @p KGlobalSettings::CompletionNone.
|
|
370 |
*/
|
|
371 |
void completion( const QString& ); |
|
372 |
||
373 |
/**
|
|
374 |
* Emitted when the shortcut for substring completion is pressed.
|
|
375 |
*/
|
|
376 |
void substringCompletion( const QString& ); |
|
377 |
||
378 |
/**
|
|
379 |
* Emitted when the text rotation key-bindings are pressed.
|
|
380 |
*
|
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
381 |
* The argument indicates which key-binding was pressed. In this
|
382 |
* case this can be either one of four values: @p PrevCompletionMatch,
|
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
383 |
* @p NextCompletionMatch, @p RotateUp or @p RotateDown. See
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
384 |
* @p setKeyBinding() for details.
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
385 |
*
|
386 |
* Note that this signal is @em NOT emitted if the completion
|
|
387 |
* mode is set to CompletionNone.
|
|
388 |
*/
|
|
389 |
void textRotation( KCompletionBase::KeyBindingType ); |
|
390 |
||
391 |
/**
|
|
392 |
* Emitted whenever the completion mode is changed by the user
|
|
393 |
* through the context menu.
|
|
394 |
*/
|
|
395 |
void completionModeChanged( KGlobalSettings::Completion ); |
|
396 |
||
397 |
/**
|
|
398 |
* Emitted before the context menu is displayed.
|
|
399 |
*
|
|
400 |
* The signal allows you to add your own entries into the context menu.
|
|
401 |
* Note that you MUST NOT store the pointer to the QPopupMenu since it is
|
|
402 |
* created and deleted on demand. Otherwise, you can crash your app.
|
|
403 |
*
|
|
404 |
* @param p the context menu about to be displayed
|
|
405 |
*/
|
|
406 |
void aboutToShowContextMenu( QPopupMenu * p ); |
|
407 |
||
408 |
public slots: |
|
409 |
||
410 |
/**
|
|
411 |
* Iterates through all possible matches of the completed text
|
|
412 |
* or the history list.
|
|
413 |
*
|
|
414 |
* Depending on the value of the argument, this function either
|
|
415 |
* iterates through the history list of this widget or the all
|
|
416 |
* possible matches in whenever multiple matches result from a
|
|
417 |
* text completion request. Note that the all-possible-match
|
|
418 |
* iteration will not work if there are no previous matches, i.e.
|
|
419 |
* no text has been completed and the *nix shell history list
|
|
420 |
* rotation is only available if the insertion policy for this
|
|
421 |
* widget is set either @p QComobBox::AtTop or @p QComboBox::AtBottom.
|
|
422 |
* For other insertion modes whatever has been typed by the user
|
|
423 |
* when the rotation event was initiated will be lost.
|
|
424 |
*
|
|
425 |
* @param type The key-binding invoked.
|
|
426 |
*/
|
|
427 |
void rotateText( KCompletionBase::KeyBindingType type ); |
|
428 |
||
429 |
/**
|
|
430 |
* Sets the completed text in the line-edit appropriately.
|
|
431 |
*
|
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
432 |
* This function is a re-implementation of @p setCompletedText.
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
433 |
*/
|
434 |
virtual void setCompletedText( const QString& ); |
|
435 |
||
436 |
/**
|
|
437 |
* Sets @p items into the completion-box if completionMode() is
|
|
438 |
* CompletionPopup. The popup will be shown immediately.
|
|
439 |
*/
|
|
440 |
void setCompletedItems( const QStringList& items ); |
|
441 |
||
442 |
/**
|
|
443 |
* Selects the first item that matches @p item. If there is no such item,
|
|
444 |
* it is inserted at position @p index if @p insert is true. Otherwise,
|
|
445 |
* no item is selected.
|
|
446 |
*/
|
|
447 |
void setCurrentItem( const QString& item, bool insert = false, int index = -1 ); |
|
2
by Jonathan Riddell
Import upstream version 3.5.0 |
448 |
|
1
by Jonathan Riddell
Import upstream version 3.4.0 |
449 |
/**
|
450 |
* Simply calls QComboBox' implementation. Only here to not become
|
|
451 |
* shadowed.
|
|
452 |
*/
|
|
453 |
void setCurrentItem(int index) { QComboBox::setCurrentItem(index); } |
|
454 |
||
455 |
protected slots: |
|
456 |
||
457 |
/**
|
|
458 |
* @deprecated
|
|
459 |
*/
|
|
11
by Jonathan Riddell
Import upstream version 3.5.8 |
460 |
virtual void itemSelected( QListBoxItem* ) {} |
1
by Jonathan Riddell
Import upstream version 3.4.0 |
461 |
|
462 |
/**
|
|
463 |
* Completes text according to the completion mode.
|
|
464 |
*
|
|
465 |
* Note: this method is @p not invoked if the completion mode is
|
|
466 |
* set to CompletionNone. Also if the mode is set to @p CompletionShell
|
|
467 |
* and multiple matches are found, this method will complete the
|
|
468 |
* text to the first match with a beep to inidicate that there are
|
|
469 |
* more matches. Then any successive completion key event iterates
|
|
470 |
* through the remaining matches. This way the rotation functionality
|
|
471 |
* is left to iterate through the list as usual.
|
|
472 |
*/
|
|
473 |
virtual void makeCompletion( const QString& ); |
|
474 |
||
475 |
protected: |
|
476 |
/*
|
|
477 |
* This function simply sets the lineedit text and
|
|
478 |
* highlights the text appropriately if the boolean
|
|
479 |
* value is set to true.
|
|
480 |
*
|
|
481 |
* @param
|
|
482 |
* @param
|
|
483 |
*/
|
|
484 |
virtual void setCompletedText( const QString& /* */, bool /*marked*/ ); |
|
485 |
||
486 |
/**
|
|
487 |
* Reimplemented for internal reasons, the API is not affected.
|
|
488 |
*/
|
|
489 |
virtual void create( WId = 0, bool initializeWindow = true, |
|
490 |
bool destroyOldWindow = true ); |
|
491 |
||
492 |
virtual void wheelEvent( QWheelEvent *ev ); |
|
493 |
||
494 |
private slots: |
|
495 |
void lineEditDeleted(); |
|
496 |
||
497 |
private: |
|
498 |
/**
|
|
499 |
* Initializes the variables upon construction.
|
|
500 |
*/
|
|
501 |
void init(); |
|
502 |
bool m_bEnableMenu; // ### BCI: unused, remove in KDE4 |
|
503 |
bool m_trapReturnKey; // ### BCI: unused, remove in KDE4 |
|
504 |
||
505 |
protected: |
|
506 |
virtual void virtual_hook( int id, void* data ); |
|
507 |
||
508 |
private: |
|
509 |
class KComboBoxPrivate; |
|
510 |
KComboBoxPrivate* const d; |
|
511 |
};
|
|
512 |
||
513 |
||
514 |
class KPixmapProvider; |
|
515 |
||
516 |
/**
|
|
517 |
* @short A combobox for offering a history and completion
|
|
518 |
*
|
|
519 |
* A combobox which implements a history like a unix shell. You can navigate
|
|
520 |
* through all the items by using the Up or Down arrows (configurable of
|
|
521 |
* course). Additionally, weighted completion is available. So you should
|
|
522 |
* load and save the completion list to preserve the weighting between
|
|
523 |
* sessions.
|
|
524 |
*
|
|
525 |
* KHistoryCombo obeys the HISTCONTROL environment variable to determine
|
|
526 |
* whether duplicates in the history should be tolerated in
|
|
527 |
* addToHistory() or not. During construction of KHistoryCombo,
|
|
528 |
* duplicates will be disabled when HISTCONTROL is set to "ignoredups" or
|
|
529 |
* "ignoreboth". Otherwise, duplicates are enabled by default.
|
|
530 |
*
|
|
531 |
* @author Carsten Pfeiffer <pfeiffer@kde.org>
|
|
532 |
*/
|
|
533 |
class KDEUI_EXPORT KHistoryCombo : public KComboBox |
|
534 |
{
|
|
535 |
Q_OBJECT
|
|
536 |
Q_PROPERTY( QStringList historyItems READ historyItems WRITE setHistoryItems ) |
|
537 |
||
538 |
public: |
|
539 |
/**
|
|
540 |
* Constructs a "read-write" combobox. A read-only history combobox
|
|
541 |
* doesn't make much sense, so it is only available as read-write.
|
|
542 |
* Completion will be used automatically for the items in the combo.
|
|
543 |
*
|
|
544 |
* The insertion-policy is set to NoInsertion, you have to add the items
|
|
545 |
* yourself via the slot addToHistory. If you want every item added,
|
|
546 |
* use
|
|
547 |
*
|
|
548 |
* \code
|
|
549 |
* connect( combo, SIGNAL( activated( const QString& )),
|
|
550 |
* combo, SLOT( addToHistory( const QString& ))); |
|
551 |
* \endcode |
|
552 |
*
|
|
553 |
* Use QComboBox::setMaxCount() to limit the history. |
|
554 |
*
|
|
555 |
* @p parent the parent object of this widget. |
|
556 |
* @p name the name of this widget. |
|
557 |
*/
|
|
558 |
KHistoryCombo( QWidget *parent = 0L, const char *name = 0L ); |
|
559 |
||
560 |
// ### merge these two constructors
|
|
561 |
/**
|
|
562 |
* Same as the previous constructor, but additionally has the option
|
|
563 |
* to specify whether you want to let KHistoryCombo handle completion
|
|
564 |
* or not. If set to @p true, KHistoryCombo will sync the completion to the
|
|
565 |
* contents of the combobox.
|
|
566 |
*/
|
|
567 |
KHistoryCombo( bool useCompletion, |
|
568 |
QWidget *parent = 0L, const char *name = 0L ); |
|
569 |
||
570 |
/**
|
|
571 |
* Destructs the combo, the completion-object and the pixmap-provider
|
|
572 |
*/
|
|
573 |
~KHistoryCombo(); |
|
574 |
||
575 |
/**
|
|
576 |
* Inserts @p items into the combobox. @p items might get
|
|
577 |
* truncated if it is longer than maxCount()
|
|
578 |
*
|
|
579 |
* @see historyItems
|
|
580 |
*/
|
|
581 |
inline void setHistoryItems( QStringList items ) { |
|
582 |
setHistoryItems(items, false); |
|
583 |
}
|
|
584 |
||
585 |
/**
|
|
586 |
* Inserts @p items into the combobox. @p items might get
|
|
587 |
* truncated if it is longer than maxCount()
|
|
588 |
*
|
|
589 |
* Set @p setCompletionList to true, if you don't have a list of
|
|
590 |
* completions. This tells KHistoryCombo to use all the items for the
|
|
591 |
* completion object as well.
|
|
592 |
* You won't have the benefit of weighted completion though, so normally
|
|
593 |
* you should do something like
|
|
594 |
* \code
|
|
595 |
* KConfig *config = kapp->config();
|
|
596 |
* QStringList list;
|
|
597 |
*
|
|
598 |
* // load the history and completion list after creating the history combo
|
|
599 |
* list = config->readListEntry( "Completion list" );
|
|
600 |
* combo->completionObject()->setItems( list );
|
|
601 |
* list = config->readListEntry( "History list" );
|
|
602 |
* combo->setHistoryItems( list );
|
|
603 |
*
|
|
604 |
* [...]
|
|
605 |
*
|
|
606 |
* // save the history and completion list when the history combo is
|
|
607 |
* // destroyed
|
|
608 |
* list = combo->completionObject()->items()
|
|
609 |
* config->writeEntry( "Completion list", list );
|
|
610 |
* list = combo->historyItems();
|
|
611 |
* config->writeEntry( "History list", list );
|
|
612 |
* \endcode
|
|
613 |
*
|
|
614 |
* Be sure to use different names for saving with KConfig if you have more
|
|
615 |
* than one KHistoryCombo.
|
|
616 |
*
|
|
617 |
* Note: When @p setCompletionList is true, the items are inserted into the
|
|
618 |
* KCompletion object with mode KCompletion::Insertion and the mode is set
|
|
619 |
* to KCompletion::Weighted afterwards.
|
|
620 |
*
|
|
621 |
* @see historyItems
|
|
622 |
* @see KComboBox::completionObject
|
|
623 |
* @see KCompletion::setItems
|
|
624 |
* @see KCompletion::items
|
|
625 |
*/
|
|
626 |
void setHistoryItems( QStringList items, bool setCompletionList ); |
|
627 |
||
628 |
/**
|
|
629 |
* Returns the list of history items. Empty, when this is not a read-write
|
|
630 |
* combobox.
|
|
631 |
*
|
|
632 |
* @see setHistoryItems
|
|
633 |
*/
|
|
634 |
QStringList historyItems() const; |
|
635 |
||
636 |
/**
|
|
637 |
* Removes all items named @p item.
|
|
638 |
*
|
|
639 |
* @return @p true if at least one item was removed.
|
|
640 |
*
|
|
641 |
* @see addToHistory
|
|
642 |
*/
|
|
643 |
bool removeFromHistory( const QString& item ); |
|
644 |
||
645 |
/**
|
|
646 |
* Sets a pixmap provider, so that items in the combobox can have a pixmap.
|
|
647 |
* KPixmapProvider is just an abstract class with the one pure virtual
|
|
648 |
* method KPixmapProvider::pixmapFor(). This method is called whenever
|
|
649 |
* an item is added to the KHistoryComboBox. Implement it to return your
|
|
650 |
* own custom pixmaps, or use the KURLPixmapProvider from libkio,
|
|
651 |
* which uses KMimeType::pixmapForURL to resolve icons.
|
|
652 |
*
|
|
653 |
* Set @p prov to 0L if you want to disable pixmaps. Default no pixmaps.
|
|
654 |
*
|
|
655 |
* @see pixmapProvider
|
|
656 |
*/
|
|
657 |
void setPixmapProvider( KPixmapProvider *prov ); |
|
658 |
||
659 |
/**
|
|
660 |
* @returns the current pixmap provider.
|
|
661 |
* @see setPixmapProvider
|
|
662 |
* @see KPixmapProvider
|
|
663 |
*/
|
|
664 |
KPixmapProvider * pixmapProvider() const { return myPixProvider; } |
|
665 |
||
666 |
/**
|
|
667 |
* Resets the current position of the up/down history. Call this
|
|
668 |
* when you manually call setCurrentItem() or clearEdit().
|
|
669 |
*/
|
|
670 |
void reset() { slotReset(); } |
|
671 |
||
672 |
public slots: |
|
673 |
/**
|
|
674 |
* Adds an item to the end of the history list and to the completion list.
|
|
675 |
* If maxCount() is reached, the first item of the list will be
|
|
676 |
* removed.
|
|
677 |
*
|
|
678 |
* If the last inserted item is the same as @p item, it will not be
|
|
679 |
* inserted again.
|
|
680 |
*
|
|
681 |
* If duplicatesEnabled() is false, any equal existing item will be
|
|
682 |
* removed before @p item is added.
|
|
683 |
*
|
|
684 |
* Note: By using this method and not the Q and KComboBox insertItem()
|
|
685 |
* methods, you make sure that the combobox stays in sync with the
|
|
686 |
* completion. It would be annoying if completion would give an item
|
|
687 |
* not in the combobox, and vice versa.
|
|
688 |
*
|
|
689 |
* @see removeFromHistory
|
|
690 |
* @see QComboBox::setDuplicatesEnabled
|
|
691 |
*/
|
|
692 |
void addToHistory( const QString& item ); |
|
693 |
||
694 |
/**
|
|
695 |
* Clears the history and the completion list.
|
|
696 |
*/
|
|
697 |
void clearHistory(); |
|
698 |
||
699 |
signals: |
|
700 |
/**
|
|
701 |
* Emitted when the history was cleared by the entry in the popup menu.
|
|
702 |
*/
|
|
703 |
void cleared(); |
|
704 |
||
705 |
protected: |
|
706 |
/**
|
|
707 |
* Handling key-events, the shortcuts to rotate the items.
|
|
708 |
*/
|
|
709 |
virtual void keyPressEvent( QKeyEvent * ); |
|
710 |
||
711 |
/**
|
|
712 |
* Handling wheel-events, to rotate the items.
|
|
713 |
*/
|
|
714 |
virtual void wheelEvent( QWheelEvent *ev ); |
|
715 |
||
716 |
/**
|
|
717 |
* Inserts @p items into the combo, honoring pixmapProvider()
|
|
718 |
* Does not update the completionObject.
|
|
719 |
*
|
|
720 |
* Note: duplicatesEnabled() is not honored here.
|
|
721 |
*
|
|
722 |
* Called from setHistoryItems() and setPixmapProvider()
|
|
723 |
*/
|
|
724 |
void insertItems( const QStringList& items ); |
|
725 |
||
726 |
/**
|
|
727 |
* @returns if we can modify the completion object or not.
|
|
728 |
*/
|
|
729 |
bool useCompletion() const { return compObj(); } |
|
730 |
||
731 |
private slots: |
|
732 |
/**
|
|
733 |
* Resets the iterate index to -1
|
|
734 |
*/
|
|
735 |
void slotReset(); |
|
736 |
||
737 |
/**
|
|
738 |
* Called from the popupmenu,
|
|
739 |
* calls clearHistory() and emits cleared()
|
|
740 |
*/
|
|
741 |
void slotClear(); |
|
742 |
||
743 |
/**
|
|
744 |
* Appends our own context menu entry.
|
|
745 |
*/
|
|
746 |
void addContextMenuItems( QPopupMenu* ); |
|
747 |
||
748 |
private: |
|
749 |
void init( bool useCompletion ); |
|
750 |
void rotateUp(); |
|
751 |
void rotateDown(); |
|
752 |
||
753 |
/**
|
|
754 |
* The current position (index) in the combobox, used for Up and Down
|
|
755 |
*/
|
|
756 |
int myIterateIndex; |
|
757 |
||
758 |
/**
|
|
759 |
* The text typed before Up or Down was pressed.
|
|
760 |
*/
|
|
761 |
QString myText; |
|
762 |
||
763 |
/**
|
|
764 |
* Indicates that the user at least once rotated Up through the entire list
|
|
765 |
* Needed to allow going back after rotation.
|
|
766 |
*/
|
|
767 |
bool myRotated; |
|
768 |
KPixmapProvider *myPixProvider; |
|
769 |
||
770 |
protected: |
|
771 |
virtual void virtual_hook( int id, void* data ); |
|
772 |
private: |
|
773 |
class KHistoryComboPrivate; |
|
774 |
KHistoryComboPrivate* const d; |
|
775 |
};
|
|
776 |
||
777 |
||
778 |
#endif
|
|
779 |