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 | |
29 | class QLineEdit; |
30 | class ; |
31 | |
32 | class KCompletionBox; |
33 | class 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 | */ |
148 | class 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 | |
155 | public: |
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 ( bool ); |
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 | |
379 | Q_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 ( QMenu * p ); |
442 | |
443 | public 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 | |
485 | protected 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 | |
500 | protected: |
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 | |
521 | private Q_SLOTS: |
522 | void lineEditDeleted(); |
523 | |
524 | private: |
525 | /** |
526 | * Initializes the variables upon construction. |
527 | */ |
528 | void init(); |
529 | |
530 | private: |
531 | class KComboBoxPrivate; |
532 | KComboBoxPrivate* const d; |
533 | }; |
534 | |
535 | |
536 | |
537 | #endif |
538 | |
539 | |