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 KCOMBOBOX_H
23#define KCOMBOBOX_H
24
25#include <QtGui/QComboBox>
26
27#include <kcompletion.h>
28
29class QLineEdit;
30class QMenu;
31
32class KCompletionBox;
33class KUrl;
34
35/*
36 * ### KDE 5: On all methods that it is said that a prettyUrl will be used, it
37 * would be nice to add a flag to the method for forcing the pretty
38 * url or not. (ereslibre)
39 */
40
41/**
42 * @short An enhanced combo box.
43 *
44 * A combined button, line-edit and a popup list widget.
45 *
46 * \b Detail \n
47 *
48 * This widget inherits from QComboBox and implements the following
49 * additional functionalities: a completion object that provides both automatic
50 * and manual text completion as well as text rotation features, configurable
51 * key-bindings to activate these features, and a popup-menu item that can be
52 * used to allow the user to change the text completion mode on the fly.
53 *
54 * To support these new features KComboBox emits a few additional signals
55 * such as completion( const QString& ) and textRotation( KeyBindingType ).
56 * The completion signal can be connected to a slot that will assist the user in
57 * filling out the remaining text while the rotation signal can be used to traverse
58 * through all possible matches whenever text completion results in multiple matches.
59 * Additionally, a returnPressed() and a returnPressed( const QString& )
60 * signals are emitted when the user presses the Enter/Return key.
61 *
62 * KCombobox by default creates a completion object when you invoke the
63 * completionObject( bool ) member function for the first time or
64 * explicitly use setCompletionObject( KCompletion*, bool ) to assign your
65 * own completion object. Additionally, to make this widget more functional,
66 * KComboBox will by default handle text rotation and completion events
67 * internally whenever a completion object is created through either one of the
68 * methods mentioned above. If you do not need this functionality, simply use
69 * KCompletionBase::setHandleSignals(bool) or alternatively set the boolean
70 * parameter in the @p setCompletionObject call to false.
71 *
72 * Beware: The completion object can be deleted on you, especially if a call
73 * such as setEditable(false) is made. Store the pointer at your own risk,
74 * and consider using QPointer<KCompletion>.
75 *
76 * The default key-bindings for completion and rotation is determined from the
77 * global settings in KStandardShortcut. These values, however, can be overridden
78 * locally by invoking KCompletionBase::setKeyBinding(). The values can
79 * easily be reverted back to the default setting, by simply calling
80 * useGlobalSettings(). An alternate method would be to default individual
81 * key-bindings by usning setKeyBinding() with the default second argument.
82 *
83 * A non-editable combobox only has one completion mode, @p CompletionAuto.
84 * Unlike an editable combobox the CompletionAuto mode, works by matching
85 * any typed key with the first letter of entries in the combobox. Please note
86 * that if you call setEditable( false ) to change an editable combobox to a
87 * non-editable one, the text completion object associated with the combobox will
88 * no longer exist unless you created the completion object yourself and assigned
89 * it to this widget or you called setAutoDeleteCompletionObject( false ). In other
90 * words do not do the following:
91 *
92 * \code
93 * KComboBox* combo = new KComboBox(true, this);
94 * KCompletion* comp = combo->completionObject();
95 * combo->setEditable( false );
96 * comp->clear(); // CRASH: completion object does not exist anymore.
97 * \endcode
98 *
99 *
100 * A read-only KComboBox will have the same background color as a
101 * disabled KComboBox, but its foreground color will be the one used for
102 * the read-write mode. This differs from QComboBox's implementation
103 * and is done to give visual distinction between the three different modes:
104 * disabled, read-only, and read-write.
105 *
106 * \b Usage \n
107 *
108 * To enable the basic completion feature:
109 *
110 * \code
111 * KComboBox *combo = new KComboBox( true, this );
112 * KCompletion *comp = combo->completionObject();
113 * // Connect to the return pressed signal - optional
114 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
115 *
116 * // Provide the to be completed strings. Note that those are separate from the combo's
117 * // contents.
118 * comp->insertItems( someQStringList );
119 * \endcode
120 *
121 * To use your own completion object:
122 *
123 * \code
124 * KComboBox *combo = new KComboBox( this );
125 * KUrlCompletion *comp = new KUrlCompletion();
126 * combo->setCompletionObject( comp );
127 * // Connect to the return pressed signal - optional
128 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
129 * \endcode
130 *
131 * Note that you have to either delete the allocated completion object
132 * when you don't need it anymore, or call
133 * setAutoDeleteCompletionObject( true );
134 *
135 * Miscellaneous function calls:
136 *
137 * \code
138 * // Tell the widget not to handle completion and rotation
139 * combo->setHandleSignals( false );
140 * // Set your own completion key for manual completions.
141 * combo->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
142 * \endcode
143 *
144 * \image html kcombobox.png "KDE Combo Boxes, one non-editable, one editable with KUrlCompletion"
145 *
146 * @author Dawit Alemayehu <adawit@kde.org>
147 */
148class KDEUI_EXPORT KComboBox : public QComboBox, public KCompletionBase //krazy:exclude=qclasses
149{
150 Q_OBJECT
151 Q_PROPERTY( bool autoCompletion READ autoCompletion WRITE setAutoCompletion )
152 Q_PROPERTY( bool urlDropsEnabled READ urlDropsEnabled WRITE setUrlDropsEnabled )
153 Q_PROPERTY( bool trapReturnKey READ trapReturnKey WRITE setTrapReturnKey )
154
155public:
156
157 /**
158 * Constructs a read-only or rather select-only combo box with a
159 * parent object and a name.
160 *
161 * @param parent The parent object of this widget
162 */
163 explicit KComboBox( QWidget *parent=0 );
164
165 /**
166 * Constructs a "read-write" or "read-only" combo box depending on
167 * the value of the first argument( @p rw ) with a parent, a
168 * name.
169 *
170 * @param rw When @p true, widget will be editable.
171 * @param parent The parent object of this widget.
172 */
173 explicit KComboBox( bool rw, QWidget *parent=0 );
174
175 /**
176 * Destructor.
177 */
178 virtual ~KComboBox();
179
180 /**
181 * Deprecated to reflect Qt api changes
182 * @deprecated
183 */
184#ifndef KDE_NO_DEPRECATED
185 KDE_DEPRECATED void insertURL( const KUrl& url, int index = -1 )
186 { insertUrl( index < 0 ? count() : index, url ); }
187 KDE_DEPRECATED void insertURL( const QPixmap& pixmap, const KUrl& url, int index = -1 )
188 { insertUrl( index < 0 ? count() : index, QIcon(pixmap), url ); }
189 KDE_DEPRECATED void changeURL( const KUrl& url, int index )
190 { changeUrl( index, url ); }
191 KDE_DEPRECATED void changeURL( const QPixmap& pixmap, const KUrl& url, int index )
192 { changeUrl( index, QIcon(pixmap), url ); }
193#endif
194
195 /**
196 * Sets @p url into the edit field of the combobox. It uses
197 * KUrl::prettyUrl() so that the url is properly decoded for
198 * displaying.
199 */
200 void setEditUrl( const KUrl& url );
201
202 /**
203 * Appends @p url to the combobox.
204 * KUrl::prettyUrl() is used so that the url is properly decoded
205 * for displaying.
206 */
207 void addUrl( const KUrl& url );
208
209 /**
210 * Appends @p url with the icon &p icon to the combobox.
211 * KUrl::prettyUrl() is used so that the url is properly decoded
212 * for displaying.
213 */
214 void addUrl( const QIcon& icon, const KUrl& url );
215
216 /**
217 * Inserts @p url at position @p index into the combobox.
218 * KUrl::prettyUrl() is used so that the url is properly decoded
219 * for displaying.
220 */
221 void insertUrl( int index, const KUrl& url );
222
223 /**
224 * Inserts @p url with the pixmap &p pixmap at position @p index into
225 * the combobox. KUrl::prettyUrl() is used so that the url is
226 * properly decoded for displaying.
227 */
228 void insertUrl( int index, const QIcon& icon, const KUrl& url );
229
230 /**
231 * Replaces the item at position @p index with @p url.
232 * KUrl::prettyUrl() is used so that the url is properly decoded
233 * for displaying.
234 */
235 void changeUrl( int index, const KUrl& url );
236
237 /**
238 * Replaces the item at position @p index with @p url and icon @p icon.
239 * KUrl::prettyUrl() is used so that the url is properly decoded
240 * for displaying.
241 */
242 void changeUrl( int index , const QIcon& icon, const KUrl& url);
243
244 /**
245 * Returns the current cursor position.
246 *
247 * This method always returns a -1 if the combo-box is @em not
248 * editable (read-write).
249 *
250 * @return Current cursor position.
251 */
252 int cursorPosition() const;
253
254 /**
255 * Re-implemented from QComboBox.
256 *
257 * If @p true, the completion mode will be set to automatic.
258 * Otherwise, it is defaulted to the global setting. This
259 * method has been replaced by the more comprehensive
260 * setCompletionMode().
261 *
262 * @param autocomplete Flag to enable/disable automatic completion mode.
263 */
264 virtual void setAutoCompletion( bool autocomplete );
265
266 /**
267 * Re-implemented from QComboBox.
268 *
269 * Returns @p true if the current completion mode is set
270 * to automatic. See its more comprehensive replacement
271 * completionMode().
272 *
273 * @return @p true when completion mode is automatic.
274 */
275 bool autoCompletion() const;
276
277 /**
278 * Enables or disable the popup (context) menu.
279 *
280 * This method only works if this widget is editable, i.e. read-write and
281 * allows you to enable/disable the context menu. It does nothing if invoked
282 * for a none-editable combo-box.
283 *
284 * By default, the context menu is created if this widget is editable.
285 * Call this function with the argument set to false to disable the popup
286 * menu.
287 *
288 * @param showMenu If @p true, show the context menu.
289 * @deprecated use setContextMenuPolicy
290 */
291#ifndef KDE_NO_DEPRECATED
292 virtual KDE_DEPRECATED void setContextMenuEnabled( bool showMenu );
293#endif
294
295 /**
296 * Enables/Disables handling of URL drops. If enabled and the user
297 * drops an URL, the decoded URL will be inserted. Otherwise the default
298 * behavior of QComboBox is used, which inserts the encoded URL.
299 *
300 * @param enable If @p true, insert decoded URLs
301 */
302 void setUrlDropsEnabled( bool enable );
303
304 /**
305 * Returns @p true when decoded URL drops are enabled
306 */
307 bool urlDropsEnabled() const;
308
309 /**
310 * Convenience method which iterates over all items and checks if
311 * any of them is equal to @p text.
312 *
313 * If @p text is an empty string, @p false
314 * is returned.
315 *
316 * @return @p true if an item with the string @p text is in the combobox.
317 */
318 bool contains( const QString& text ) const;
319
320 /**
321 * By default, KComboBox recognizes Key_Return and Key_Enter
322 * and emits the returnPressed() signals, but it also lets the
323 * event pass, for example causing a dialog's default-button to
324 * be called.
325 *
326 * Call this method with @p trap equal to true to make KComboBox
327 * stop these events. The signals will still be emitted of course.
328 *
329 * Only affects read-writable comboboxes.
330 *
331 * @see setTrapReturnKey()
332 */
333 void setTrapReturnKey( bool trap );
334
335 /**
336 * @return @p true if keyevents of Key_Return or Key_Enter will
337 * be stopped or if they will be propagated.
338 *
339 * @see setTrapReturnKey ()
340 */
341 bool trapReturnKey() const;
342
343 /**
344 * Re-implemented for internal reasons. API not affected.
345 */
346 virtual bool eventFilter( QObject *, QEvent * );
347
348 /**
349 * @returns the completion-box, that is used in completion mode
350 * KGlobalSettings::CompletionPopup and KGlobalSettings::CompletionPopupAuto.
351 * This method will create a completion-box by calling
352 * KLineEdit::completionBox, if none is there, yet.
353 *
354 * @param create Set this to false if you don't want the box to be created
355 * i.e. to test if it is available.
356 */
357 KCompletionBox * completionBox( bool create = true );
358
359 /**
360 * Re-implemented for internal reasons. API remains unaffected.
361 * Note that QComboBox::setLineEdit is not virtual in Qt4, do not
362 * use a KComboBox in a QComboBox pointer.
363 *
364 * NOTE: Only editable comboboxes can have a line editor. As such
365 * any attempt to assign a line-edit to a non-editable combobox will
366 * simply be ignored.
367 */
368 virtual void setLineEdit( QLineEdit * );
369
370 /**
371 * "Re-implemented" so that setEditable(true) creates a KLineEdit
372 * instead of QLineEdit.
373 *
374 * Note that QComboBox::setEditable is not virtual, so do not
375 * use a KComboBox in a QComboBox pointer.
376 */
377 void setEditable(bool editable);
378
379Q_SIGNALS:
380 /**
381 * Emitted when the user presses the Enter key.
382 *
383 * Note that this signal is only emitted when the widget is editable.
384 */
385 void returnPressed();
386
387 /**
388 * Emitted when the user presses the Enter key.
389 *
390 * The argument is the current text being edited. This signal is just like
391 * returnPressed() except it contains the current text as its argument.
392 *
393 * Note that this signal is only emitted when the
394 * widget is editable.
395 */
396 void returnPressed( const QString& );
397
398 /**
399 * Emitted when the completion key is pressed.
400 *
401 * The argument is the current text being edited.
402 *
403 * Note that this signal is @em not available when the widget is non-editable
404 * or the completion mode is set to @p KGlobalSettings::CompletionNone.
405 */
406 void completion( const QString& );
407
408 /**
409 * Emitted when the shortcut for substring completion is pressed.
410 */
411 void substringCompletion( const QString& );
412
413 /**
414 * Emitted when the text rotation key-bindings are pressed.
415 *
416 * The argument indicates which key-binding was pressed. In this case this
417 * can be either one of four values: @p PrevCompletionMatch,
418 * @p NextCompletionMatch, @p RotateUp or @p RotateDown. See
419 * KCompletionBase::setKeyBinding() for details.
420 *
421 * Note that this signal is @em NOT emitted if the completion
422 * mode is set to CompletionNone.
423 */
424 void textRotation( KCompletionBase::KeyBindingType );
425
426 /**
427 * Emitted whenever the completion mode is changed by the user
428 * through the context menu.
429 */
430 void completionModeChanged( KGlobalSettings::Completion );
431
432 /**
433 * Emitted before the context menu is displayed.
434 *
435 * The signal allows you to add your own entries into the context menu.
436 * Note that you MUST NOT store the pointer to the QPopupMenu since it is
437 * created and deleted on demand. Otherwise, you can crash your app.
438 *
439 * @param p the context menu about to be displayed
440 */
441 void aboutToShowContextMenu( QMenu * p );
442
443public Q_SLOTS:
444
445 /**
446 * Iterates through all possible matches of the completed text
447 * or the history list.
448 *
449 * Depending on the value of the argument, this function either
450 * iterates through the history list of this widget or the all
451 * possible matches in whenever multiple matches result from a
452 * text completion request. Note that the all-possible-match
453 * iteration will not work if there are no previous matches, i.e.
454 * no text has been completed and the *nix shell history list
455 * rotation is only available if the insertion policy for this
456 * widget is set either @p QComobBox::AtTop or @p QComboBox::AtBottom.
457 * For other insertion modes whatever has been typed by the user
458 * when the rotation event was initiated will be lost.
459 *
460 * @param type The key-binding invoked.
461 */
462 void rotateText( KCompletionBase::KeyBindingType type );
463
464 /**
465 * Sets the completed text in the line-edit appropriately.
466 *
467 * This function is an implementation for
468 * KCompletionBase::setCompletedText.
469 */
470 virtual void setCompletedText( const QString& );
471
472 /**
473 * Sets @p items into the completion-box if completionMode() is
474 * CompletionPopup. The popup will be shown immediately.
475 */
476 void setCompletedItems( const QStringList& items, bool autosubject = true );
477
478 /**
479 * Selects the first item that matches @p item. If there is no such item,
480 * it is inserted at position @p index if @p insert is true. Otherwise,
481 * no item is selected.
482 */
483 void setCurrentItem( const QString& item, bool insert = false, int index = -1 );
484
485protected Q_SLOTS:
486
487 /**
488 * Completes text according to the completion mode.
489 *
490 * Note: this method is @p not invoked if the completion mode is
491 * set to CompletionNone. Also if the mode is set to @p CompletionShell
492 * and multiple matches are found, this method will complete the
493 * text to the first match with a beep to inidicate that there are
494 * more matches. Then any successive completion key event iterates
495 * through the remaining matches. This way the rotation functionality
496 * is left to iterate through the list as usual.
497 */
498 virtual void makeCompletion( const QString& );
499
500protected:
501 /*
502 * This function simply sets the lineedit text and
503 * highlights the text appropriately if the boolean
504 * value is set to true.
505 *
506 * @param
507 * @param
508 */
509 virtual void setCompletedText( const QString& /* */, bool /*marked*/ );
510
511 /**
512 * Reimplemented for internal reasons, the API is not affected.
513 */
514 virtual void create( WId = 0, bool initializeWindow = true,
515 bool destroyOldWindow = true );
516
517 virtual void wheelEvent( QWheelEvent *ev );
518
519 virtual QSize minimumSizeHint() const;
520
521private Q_SLOTS:
522 void lineEditDeleted();
523
524private:
525 /**
526 * Initializes the variables upon construction.
527 */
528 void init();
529
530private:
531 class KComboBoxPrivate;
532 KComboBoxPrivate* const d;
533};
534
535
536
537#endif
538
539