author | mickeyl <mickeyl> | 2003-03-28 15:11:52 (UTC) |
---|---|---|
committer | mickeyl <mickeyl> | 2003-03-28 15:11:52 (UTC) |
commit | 11304d02942e9fa493e4e80943a828f9c65f6772 (patch) (unidiff) | |
tree | a0223c10c067e1afc70d15c2b82be3f3c15e41ae /libopie2/qt3/opieui/ocombobox.h | |
parent | b271d575fa05cf570a1a829136517761bd47e69b (diff) | |
download | opie-11304d02942e9fa493e4e80943a828f9c65f6772.zip opie-11304d02942e9fa493e4e80943a828f9c65f6772.tar.gz opie-11304d02942e9fa493e4e80943a828f9c65f6772.tar.bz2 |
skeleton and the start of libopie2, please read README, ROADMAP and STATUS and comment...
Diffstat (limited to 'libopie2/qt3/opieui/ocombobox.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | libopie2/qt3/opieui/ocombobox.h | 790 |
1 files changed, 790 insertions, 0 deletions
diff --git a/libopie2/qt3/opieui/ocombobox.h b/libopie2/qt3/opieui/ocombobox.h new file mode 100644 index 0000000..4e35b61 --- a/dev/null +++ b/libopie2/qt3/opieui/ocombobox.h | |||
@@ -0,0 +1,790 @@ | |||
1 | /* | ||
2 | This file Copyright (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de> | ||
3 | is part of the Copyright (C) 2000 Carsten Pfeiffer <pfeiffer@kde.org> | ||
4 | Opie Project Copyright (C) 2000 Dawit Alemayehu <adawit@kde.org> | ||
5 | |||
6 | =. Originally part of the KDE projects | ||
7 | .=l. | ||
8 | .>+-= | ||
9 | _;:, .> :=|. This program is free software; you can | ||
10 | .> <`_, > . <= redistribute it and/or modify it under | ||
11 | :`=1 )Y*s>-.-- : the terms of the GNU Library General Public | ||
12 | .="- .-=="i, .._ License as published by the Free Software | ||
13 | - . .-<_> .<> Foundation; either version 2 of the License, | ||
14 | ._= =} : or (at your option) any later version. | ||
15 | .%`+i> _;_. | ||
16 | .i_,=:_. -<s. This program is distributed in the hope that | ||
17 | + . -:. = it will be useful, but WITHOUT ANY WARRANTY; | ||
18 | : .. .:, . . . without even the implied warranty of | ||
19 | =_ + =;=|` MERCHANTABILITY or FITNESS FOR A | ||
20 | _.=:. : :=>`: PARTICULAR PURPOSE. See the GNU | ||
21 | ..}^=.= = ; Library General Public License for more | ||
22 | ++= -. .` .: details. | ||
23 | : = ...= . :.=- | ||
24 | -. .:....=;==+<; You should have received a copy of the GNU | ||
25 | -_. . . )=. = Library General Public License along with | ||
26 | -- :-=` this library; see the file COPYING.LIB. | ||
27 | If not, write to the Free Software Foundation, | ||
28 | Inc., 59 Temple Place - Suite 330, | ||
29 | Boston, MA 02111-1307, USA. | ||
30 | |||
31 | */ | ||
32 | |||
33 | #ifndef OCOMBOBOX_H | ||
34 | #define OCOMBOBOX_H | ||
35 | |||
36 | /* QT */ | ||
37 | |||
38 | #include <qcombobox.h> | ||
39 | |||
40 | /* OPIE */ | ||
41 | |||
42 | #include <opie2/olineedit.h> | ||
43 | #include <opie2/ocompletion.h> | ||
44 | #include <opie2/ocompletionbase.h> | ||
45 | |||
46 | /* FORWARDS */ | ||
47 | |||
48 | class QListBoxItem; | ||
49 | class QPopupMenu; | ||
50 | class OCompletionBox; | ||
51 | typedef QString OURL; | ||
52 | |||
53 | /** | ||
54 | * A combined button, line-edit and a popup list widget. | ||
55 | * | ||
56 | * @sect Detail | ||
57 | * | ||
58 | * This widget inherits from @ref QComboBox and implements | ||
59 | * the following additional functionalities: a completion | ||
60 | * object that provides both automatic and manual text | ||
61 | * completion as well as text rotation features, configurable | ||
62 | * key-bindings to activate these features, and a popup-menu | ||
63 | * item that can be used to allow the user to set text completion | ||
64 | * modes on the fly based on their preference. | ||
65 | * | ||
66 | * To support these new features OComboBox also emits a few | ||
67 | * more additional signals as well. The main ones are the | ||
68 | * @ref completion( const QString& ) and @ref textRotation( KeyBindingType ) | ||
69 | * signals. The completion signal is intended to be connected to a slot | ||
70 | * that will assist the user in filling out the remaining text while | ||
71 | * the rotation signals is intended to be used to traverse through all | ||
72 | * possible matches whenever text completion results in multiple matches. | ||
73 | * The @ref returnPressed() and @ref returnPressed( const QString& ) | ||
74 | * signal is emitted when the user presses the Enter/Return key. | ||
75 | * | ||
76 | * This widget by default creates a completion object when you invoke | ||
77 | * the @ref completionObject( bool ) member function for the first time | ||
78 | * or use @ref setCompletionObject( OCompletion*, bool ) to assign your | ||
79 | * own completion object. Additionally, to make this widget more functional, | ||
80 | * OComboBox will by default handle the text rotation and completion | ||
81 | * events internally whenever a completion object is created through either | ||
82 | * one of the methods mentioned above. If you do not need this functionality, | ||
83 | * simply use @ref OCompletionBase::setHandleSignals( bool ) or alternatively | ||
84 | * set the boolean parameter in the above methods to FALSE. | ||
85 | * | ||
86 | * The default key-bindings for completion and rotation is determined | ||
87 | * from the global settings in @ref OStdAccel. These values, however, | ||
88 | * can be overriden locally by invoking @ref OCompletionBase::setKeyBinding(). | ||
89 | * The values can easily be reverted back to the default setting, by simply | ||
90 | * calling @ref useGlobalSettings(). An alternate method would be to default | ||
91 | * individual key-bindings by usning @ref setKeyBinding() with the default | ||
92 | * second argument. | ||
93 | * | ||
94 | * Note that if this widget is not editable ( i.e. select-only ), then only | ||
95 | * one completion mode, @p CompletionAuto, will work. All the other modes are | ||
96 | * simply ignored. The @p CompletionAuto mode in this case allows you to | ||
97 | * automatically select an item from the list by trying to match the pressed | ||
98 | * keycode with the first letter of the enteries in the combo box. | ||
99 | * | ||
100 | * @sect Useage | ||
101 | * | ||
102 | * To enable the basic completion feature: | ||
103 | * | ||
104 | * <pre> | ||
105 | * OComboBox *combo = new OComboBox( true, this, "mywidget" ); | ||
106 | * OCompletion *comp = combo->completionObject(); | ||
107 | * // Connect to the return pressed signal - optional | ||
108 | * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)); | ||
109 | * </pre> | ||
110 | * | ||
111 | * To use your own completion object: | ||
112 | * | ||
113 | * <pre> | ||
114 | * OComboBox *combo = new OComboBox( this,"mywidget" ); | ||
115 | * OURLCompletion *comp = new OURLCompletion(); | ||
116 | * combo->setCompletionObject( comp ); | ||
117 | * // Connect to the return pressed signal - optional | ||
118 | * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)); | ||
119 | * </pre> | ||
120 | * | ||
121 | * Note that you have to either delete the allocated completion object | ||
122 | * when you don't need it anymore, or call | ||
123 | * setAutoDeleteCompletionObject( true ); | ||
124 | * | ||
125 | * Miscellaneous function calls: | ||
126 | * | ||
127 | * <pre> | ||
128 | * // Tell the widget not to handle completion and rotation | ||
129 | * combo->setHandleSignals( false ); | ||
130 | * // Set your own completion key for manual completions. | ||
131 | * combo->setKeyBinding( OCompletionBase::TextCompletion, Qt::End ); | ||
132 | * // Hide the context (popup) menu | ||
133 | * combo->setContextMenuEnabled( false ); | ||
134 | * // Temporarly disable signal emition | ||
135 | * combo->disableSignals(); | ||
136 | * // Default the all key-bindings to their system-wide settings. | ||
137 | * combo->useGlobalKeyBindings(); | ||
138 | * </pre> | ||
139 | * | ||
140 | * @short An enhanced combo box. | ||
141 | * @author Dawit Alemayehu <adawit@kde.org> | ||
142 | */ | ||
143 | class OComboBox : public QComboBox, public OCompletionBase | ||
144 | { | ||
145 | Q_OBJECT | ||
146 | |||
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 | |||
151 | public: | ||
152 | |||
153 | /** | ||
154 | * Constructs a read-only or rather select-only combo box with a | ||
155 | * parent object and a name. | ||
156 | * | ||
157 | * @param parent The parent object of this widget | ||
158 | * @param name The name of this widget | ||
159 | */ | ||
160 | OComboBox( QWidget *parent=0, const char *name=0 ); | ||
161 | |||
162 | /** | ||
163 | * Constructs a "read-write" or "read-only" combo box depending on | ||
164 | * the value of the first argument( @p rw ) with a parent, a | ||
165 | * name. | ||
166 | * | ||
167 | * @param rw When @p true, widget will be editable. | ||
168 | * @param parent The parent object of this widget. | ||
169 | * @param name The name of this widget. | ||
170 | */ | ||
171 | OComboBox( bool rw, QWidget *parent=0, const char *name=0 ); | ||
172 | |||
173 | /** | ||
174 | * Destructor. | ||
175 | */ | ||
176 | virtual ~OComboBox(); | ||
177 | |||
178 | /** | ||
179 | * Sets @p url into the edit field of the combobox. It uses | ||
180 | * @ref OURL::prettyURL() so that the url is properly decoded for | ||
181 | * displaying. | ||
182 | */ | ||
183 | //void setEditURL( const OURL& url ); | ||
184 | |||
185 | /** | ||
186 | * Inserts @p url at position @p index into the combobox. The item will | ||
187 | * be appended if @p index is negative. @ref OURL::prettyURL() is used | ||
188 | * so that the url is properly decoded for displaying. | ||
189 | */ | ||
190 | //void insertURL( const OURL& url, int index = -1 ); | ||
191 | |||
192 | /** | ||
193 | * Inserts @p url with the pixmap &p pixmap at position @p index into | ||
194 | * the combobox. The item will be appended if @p index is negative. | ||
195 | * @ref OURL::prettyURL() is used so that the url is properly decoded | ||
196 | * for displaying. | ||
197 | */ | ||
198 | //void insertURL( const QPixmap& pixmap, const OURL& url, int index = -1 ); | ||
199 | |||
200 | /** | ||
201 | * Replaces the item at position @p index with @p url. | ||
202 | * @ref OURL::prettyURL() is used so that the url is properly decoded | ||
203 | * for displaying. | ||
204 | */ | ||
205 | //void changeURL( const OURL& url, int index ); | ||
206 | |||
207 | /** | ||
208 | * Replaces the item at position @p index with @p url and pixmap @p pixmap. | ||
209 | * @ref OURL::prettyURL() is used so that the url is properly decoded | ||
210 | * for displaying. | ||
211 | */ | ||
212 | //void changeURL( const QPixmap& pixmap, const OURL& url, int index ); | ||
213 | |||
214 | /** | ||
215 | * Returns the current cursor position. | ||
216 | * | ||
217 | * This method always returns a -1 if the combo-box is @em not | ||
218 | * editable (read-write). | ||
219 | * | ||
220 | * @return Current cursor position. | ||
221 | */ | ||
222 | int cursorPosition() const { return ( lineEdit() ) ? lineEdit()->cursorPosition() : -1; } | ||
223 | |||
224 | /** | ||
225 | * Re-implemented from @ref QComboBox. | ||
226 | * | ||
227 | * If @p true, the completion mode will be set to automatic. | ||
228 | * Otherwise, it is defaulted to the global setting. This | ||
229 | * method has been replaced by the more comprehensive | ||
230 | * @ref setCompletionMode(). | ||
231 | * | ||
232 | * @param autocomplete Flag to enable/disable automatic completion mode. | ||
233 | */ | ||
234 | virtual void setAutoCompletion( bool autocomplete ); | ||
235 | |||
236 | /** | ||
237 | * Re-implemented from QComboBox. | ||
238 | * | ||
239 | * Returns @p true if the current completion mode is set | ||
240 | * to automatic. See its more comprehensive replacement | ||
241 | * @ref completionMode(). | ||
242 | * | ||
243 | * @return @p true when completion mode is automatic. | ||
244 | */ | ||
245 | bool autoCompletion() const { | ||
246 | return completionMode() == OGlobalSettings::CompletionAuto; | ||
247 | } | ||
248 | |||
249 | /** | ||
250 | * Enables or disable the popup (context) menu. | ||
251 | * | ||
252 | * This method only works if this widget is editable, i.e. | ||
253 | * read-write and allows you to enable/disable the context | ||
254 | * menu. It does nothing if invoked for a none-editable | ||
255 | * combo-box. Note that by default the mode changer item | ||
256 | * is made visiable whenever the context menu is enabled. | ||
257 | * Use @ref hideModechanger() if you want to hide this | ||
258 | * item. Also by default, the context menu is created if | ||
259 | * this widget is editable. Call this function with the | ||
260 | * argument set to false to disable the popup menu. | ||
261 | * | ||
262 | * @param showMenu If @p true, show the context menu. | ||
263 | * @param showMode If @p true, show the mode changer. | ||
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 | * behaviour 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, OComboBox recognizes Key_Return and Key_Enter | ||
299 | * and emits | ||
300 | * the @ref returnPressed() signals, but it also lets the event pass, | ||
301 | * for example causing a dialog's default-button to be called. | ||
302 | * | ||
303 | * Call this method with @p trap equal to true to make OComboBox | ||
304 | * stop these | ||
305 | * events. The signals will still be emitted of course. | ||
306 | * | ||
307 | * Only affects read-writable comboboxes. | ||
308 | * | ||
309 | * @see setTrapReturnKey() | ||
310 | */ | ||
311 | void setTrapReturnKey( bool trap ); | ||
312 | |||
313 | /** | ||
314 | * @return @p true if keyevents of Key_Return or Key_Enter will | ||
315 | * be stopped or if they will be propagated. | ||
316 | * | ||
317 | * @see setTrapReturnKey () | ||
318 | */ | ||
319 | bool trapReturnKey() const; | ||
320 | |||
321 | /** | ||
322 | * Re-implemented for internal reasons. API not affected. | ||
323 | * | ||
324 | * @reimplemented | ||
325 | */ | ||
326 | virtual bool eventFilter( QObject *, QEvent * ); | ||
327 | |||
328 | /** | ||
329 | * @returns the completion-box, that is used in completion mode | ||
330 | * @ref OGlobalSettings::CompletionPopup and @ref OGlobalSettings::CompletionPopupAuto. | ||
331 | * This method will create a completion-box by calling | ||
332 | * @ref OLineEdit::completionBox, if none is there, yet. | ||
333 | * | ||
334 | * @param create Set this to false if you don't want the box to be created | ||
335 | * i.e. to test if it is available. | ||
336 | */ | ||
337 | OCompletionBox * completionBox( bool create = true ); | ||
338 | |||
339 | virtual void setLineEdit( OLineEdit * ); | ||
340 | |||
341 | signals: | ||
342 | /** | ||
343 | * Emitted when the user presses the Enter key. | ||
344 | * | ||
345 | * Note that this signal is only | ||
346 | * emitted if this widget is editable. | ||
347 | */ | ||
348 | void returnPressed(); | ||
349 | |||
350 | /** | ||
351 | * Emitted when the user presses | ||
352 | * the Enter key. | ||
353 | * | ||
354 | * The argument is the current | ||
355 | * text being edited. This signal is just like | ||
356 | * @ref returnPressed() except it contains the | ||
357 | * current text as its argument. | ||
358 | * | ||
359 | * Note that this signal is only emitted if this | ||
360 | * widget is editable. | ||
361 | */ | ||
362 | void returnPressed( const QString& ); | ||
363 | |||
364 | /** | ||
365 | * This signal is emitted when the completion key | ||
366 | * is pressed. | ||
367 | * | ||
368 | * The argument is the current text | ||
369 | * being edited. | ||
370 | * | ||
371 | * Note that this signal is @em not available if this | ||
372 | * widget is non-editable or the completion mode is | ||
373 | * set to @p OGlobalSettings::CompletionNone. | ||
374 | */ | ||
375 | void completion( const QString& ); | ||
376 | |||
377 | /** | ||
378 | * Emitted when the shortcut for substring completion is pressed. | ||
379 | */ | ||
380 | void substringCompletion( const QString& ); | ||
381 | |||
382 | /** | ||
383 | * Emitted when the text rotation key-bindings are pressed. | ||
384 | * | ||
385 | * The argument indicates which key-binding was pressed. | ||
386 | * In this case this can be either one of four values: | ||
387 | * @p PrevCompletionMatch, @p NextCompletionMatch, @p RotateUp or | ||
388 | * @p RotateDown. See @ref OCompletionBase::setKeyBinding() for | ||
389 | * details. | ||
390 | * | ||
391 | * Note that this signal is @em NOT emitted if the completion | ||
392 | * mode is set to CompletionNone. | ||
393 | */ | ||
394 | void textRotation( OCompletionBase::KeyBindingType ); | ||
395 | |||
396 | /** | ||
397 | * Emitted when the user changed the completion mode by using the | ||
398 | * popupmenu. | ||
399 | */ | ||
400 | void completionModeChanged( OGlobalSettings::Completion ); | ||
401 | |||
402 | /** | ||
403 | * Emitted before the context menu is displayed. | ||
404 | * | ||
405 | * The signal allows you to add your own entries into the | ||
406 | * the context menu that is created on demand. | ||
407 | * | ||
408 | * NOTE: Do not store the pointer to the QPopupMenu | ||
409 | * provided through since it is created and deleted | ||
410 | * on demand. | ||
411 | * | ||
412 | * @param the context menu about to be displayed | ||
413 | */ | ||
414 | void aboutToShowContextMenu( QPopupMenu * ); | ||
415 | |||
416 | public slots: | ||
417 | |||
418 | /** | ||
419 | * Iterates through all possible matches of the completed text | ||
420 | * or the history list. | ||
421 | * | ||
422 | * Depending on the value of the argument, this function either | ||
423 | * iterates through the history list of this widget or the all | ||
424 | * possible matches in whenever multiple matches result from a | ||
425 | * text completion request. Note that the all-possible-match | ||
426 | * iteration will not work if there are no previous matches, i.e. | ||
427 | * no text has been completed and the *nix shell history list | ||
428 | * rotation is only available if the insertion policy for this | ||
429 | * widget is set either @p QComobBox::AtTop or @p QComboBox::AtBottom. | ||
430 | * For other insertion modes whatever has been typed by the user | ||
431 | * when the rotation event was initiated will be lost. | ||
432 | * | ||
433 | * @param type The key-binding invoked. | ||
434 | */ | ||
435 | void rotateText( OCompletionBase::KeyBindingType /* type */ ); | ||
436 | |||
437 | /** | ||
438 | * Sets the completed text in the line-edit appropriately. | ||
439 | * | ||
440 | * This function is an implementation for | ||
441 | * @ref OCompletionBase::setCompletedText. | ||
442 | */ | ||
443 | virtual void setCompletedText( const QString& ); | ||
444 | |||
445 | /** | ||
446 | * Sets @p items into the completion-box if @ref completionMode() is | ||
447 | * CompletionPopup. The popup will be shown immediately. | ||
448 | */ | ||
449 | void setCompletedItems( const QStringList& items ); | ||
450 | |||
451 | public: | ||
452 | /** | ||
453 | * Selects the first item that matches @p item. If there is no such item, | ||
454 | * it is inserted at position @p index if @p insert is true. Otherwise, | ||
455 | * no item is selected. | ||
456 | */ | ||
457 | void setCurrentItem( const QString& item, bool insert = false, int index = -1 ); | ||
458 | void setCurrentItem(int index); | ||
459 | |||
460 | protected slots: | ||
461 | |||
462 | /** | ||
463 | * @deprecated. | ||
464 | */ | ||
465 | virtual void itemSelected( QListBoxItem* ) {}; | ||
466 | |||
467 | /** | ||
468 | * Completes text according to the completion mode. | ||
469 | * | ||
470 | * Note: this method is @p not invoked if the completion mode is | ||
471 | * set to CompletionNone. Also if the mode is set to @p CompletionShell | ||
472 | * and multiple matches are found, this method will complete the | ||
473 | * text to the first match with a beep to inidicate that there are | ||
474 | * more matches. Then any successive completion key event iterates | ||
475 | * through the remaining matches. This way the rotation functionality | ||
476 | * is left to iterate through the list as usual. | ||
477 | */ | ||
478 | virtual void makeCompletion( const QString& ); | ||
479 | |||
480 | protected: | ||
481 | /* | ||
482 | * This function simply sets the lineedit text and | ||
483 | * highlights the text appropriately if the boolean | ||
484 | * value is set to true. | ||
485 | * | ||
486 | * @param | ||
487 | * @param | ||
488 | */ | ||
489 | virtual void setCompletedText( const QString& /* */, bool /*marked*/ ); | ||
490 | |||
491 | /** | ||
492 | * Reimplemented for internal reasons, the API is not affected. | ||
493 | */ | ||
494 | virtual void create( WId = 0, bool initializeWindow = true, | ||
495 | bool destroyOldWindow = true ); | ||
496 | |||
497 | private: | ||
498 | // Constants that represent the ID's of the popup menu. | ||
499 | // TODO: See if we can replace this mess with OActionMenu | ||
500 | // in the future though this is working lovely. | ||
501 | enum MenuID { | ||
502 | Default=0, | ||
503 | Cut, | ||
504 | Copy, | ||
505 | Paste, | ||
506 | Clear, | ||
507 | Unselect, | ||
508 | SelectAll, | ||
509 | NoCompletion, | ||
510 | AutoCompletion, | ||
511 | ShellCompletion, | ||
512 | PopupCompletion, | ||
513 | SemiAutoCompletion | ||
514 | }; | ||
515 | |||
516 | /** | ||
517 | * Initializes the variables upon construction. | ||
518 | */ | ||
519 | void init(); | ||
520 | /** | ||
521 | * Temporary functions to delete words back and foward until | ||
522 | * alternatives are available in QT3 (Seth Chaiklin, 21 may 2001) | ||
523 | */ | ||
524 | void deleteWordBack(); | ||
525 | void deleteWordForward(); | ||
526 | |||
527 | bool m_bEnableMenu; | ||
528 | |||
529 | // indicating if we should stop return-key events from propagating | ||
530 | bool m_trapReturnKey; | ||
531 | |||
532 | //protected: | ||
533 | // virtual void virtual_hook( int id, void* data ); | ||
534 | private: | ||
535 | class OComboBoxPrivate; | ||
536 | OComboBoxPrivate *d; | ||
537 | }; | ||
538 | |||
539 | |||
540 | class OPixmapProvider; | ||
541 | |||
542 | /** | ||
543 | * A combobox which implements a history like a unix shell. You can navigate | ||
544 | * through all the items by using the Up or Down arrows (configurable of | ||
545 | * course). Additionally, weighted completion is available. So you should | ||
546 | * load and save the completion list to preserve the weighting between | ||
547 | * sessions. | ||
548 | * | ||
549 | * @author Carsten Pfeiffer <pfeiffer@kde.org> | ||
550 | * @short A combobox for offering a history and completion | ||
551 | */ | ||
552 | class OHistoryCombo : public OComboBox | ||
553 | { | ||
554 | Q_OBJECT | ||
555 | Q_PROPERTY( QStringList historyItems READ historyItems WRITE setHistoryItems ) | ||
556 | |||
557 | public: | ||
558 | /** | ||
559 | * Constructs a "read-write" combobox. A read-only history combobox | ||
560 | * doesn't make much sense, so it is only available as read-write. | ||
561 | * Completion will be used automatically for the items in the combo. | ||
562 | * | ||
563 | * The insertion-policy is set to NoInsertion, you have to add the items | ||
564 | * yourself via the slot @ref addToHistory. If you want every item added, | ||
565 | * use | ||
566 | * | ||
567 | * <pre> | ||
568 | * connect( combo, SIGNAL( activated( const QString& )), | ||
569 | * combo, SLOT( addToHistory( const QString& ))); | ||
570 | * </pre> | ||
571 | * | ||
572 | * Use @ref QComboBox::setMaxCount() to limit the history. | ||
573 | * | ||
574 | * @p parent the parent object of this widget. | ||
575 | * @p name the name of this widget. | ||
576 | */ | ||
577 | OHistoryCombo( QWidget *parent = 0L, const char *name = 0L ); | ||
578 | |||
579 | // ### merge these two constructors | ||
580 | /** | ||
581 | * Same as the previous constructor, but additionally has the option | ||
582 | * to specify whether you want to let OHistoryCombo handle completion | ||
583 | * or not. If set to @p true, OHistoryCombo will sync the completion to the | ||
584 | * contents of the combobox. | ||
585 | */ | ||
586 | OHistoryCombo( bool useCompletion, | ||
587 | QWidget *parent = 0L, const char *name = 0L ); | ||
588 | |||
589 | /** | ||
590 | * Destructs the combo, the completion-object and the pixmap-provider | ||
591 | */ | ||
592 | ~OHistoryCombo(); | ||
593 | |||
594 | /** | ||
595 | * Inserts @p items into the combobox. @p items might get | ||
596 | * truncated if it is longer than @ref maxCount() | ||
597 | * | ||
598 | * @see #historyItems | ||
599 | */ | ||
600 | inline void setHistoryItems( QStringList items ) { | ||
601 | setHistoryItems(items, false); | ||
602 | } | ||
603 | |||
604 | /** | ||
605 | * Inserts @p items into the combobox. @p items might get | ||
606 | * truncated if it is longer than @ref maxCount() | ||
607 | * | ||
608 | * Set @p setCompletionList to true, if you don't have a list of | ||
609 | * completions. This tells OHistoryCombo to use all the items for the | ||
610 | * completion object as well. | ||
611 | * You won't have the benefit of weighted completion though, so normally | ||
612 | * you should do something like | ||
613 | * <pre> | ||
614 | * OConfig *config = kapp->config(); | ||
615 | * QStringList list; | ||
616 | * | ||
617 | * // load the history and completion list after creating the history combo | ||
618 | * list = config->readListEntry( "Completion list" ); | ||
619 | * combo->completionObject()->setItems( list ); | ||
620 | * list = config->readListEntry( "History list" ); | ||
621 | * combo->setHistoryItems( list ); | ||
622 | * | ||
623 | * [...] | ||
624 | * | ||
625 | * // save the history and completion list when the history combo is | ||
626 | * // destroyed | ||
627 | * list = combo->completionObject()->items() | ||
628 | * config->writeEntry( "Completion list", list ); | ||
629 | * list = combo->historyItems(); | ||
630 | * config->writeEntry( "History list", list ); | ||
631 | * </pre> | ||
632 | * | ||
633 | * Be sure to use different names for saving with OConfig if you have more | ||
634 | * than one OHistoryCombo. | ||
635 | * | ||
636 | * Note: When @p setCompletionList is true, the items are inserted into the | ||
637 | * OCompletion object with mode OCompletion::Insertion and the mode is set | ||
638 | * to OCompletion::Weighted afterwards. | ||
639 | * | ||
640 | * @see #historyItems | ||
641 | * @see OComboBox::completionObject | ||
642 | * @see OCompletion::setItems | ||
643 | * @see OCompletion::items | ||
644 | */ | ||
645 | void setHistoryItems( QStringList items, bool setCompletionList ); | ||
646 | |||
647 | /** | ||
648 | * Returns the list of history items. Empty, when this is not a read-write | ||
649 | * combobox. | ||
650 | * | ||
651 | * @see #setHistoryItems | ||
652 | */ | ||
653 | QStringList historyItems() const; | ||
654 | |||
655 | /** | ||
656 | * Removes all items named @p item. | ||
657 | * | ||
658 | * @return @p true if at least one item was removed. | ||
659 | * | ||
660 | * @see #addToHistory | ||
661 | */ | ||
662 | bool removeFromHistory( const QString& item ); | ||
663 | |||
664 | /** | ||
665 | * Sets a pixmap provider, so that items in the combobox can have a pixmap. | ||
666 | * @ref OPixmapProvider is just an abstract class with the one pure virtual | ||
667 | * method @ref OPixmapProvider::pixmapFor(). This method is called whenever | ||
668 | * an item is added to the OHistoryComboBox. Implement it to return your | ||
669 | * own custom pixmaps, or use the @ref OURLPixmapProvider from libkio, | ||
670 | * which uses @ref OMimeType::pixmapForURL to resolve icons. | ||
671 | * | ||
672 | * Set @p prov to 0L if you want to disable pixmaps. Default no pixmaps. | ||
673 | * | ||
674 | * @see #pixmapProvider | ||
675 | */ | ||
676 | void setPixmapProvider( OPixmapProvider *prov ); | ||
677 | |||
678 | /** | ||
679 | * @returns the current pixmap provider. | ||
680 | * @see #setPixmapProvider | ||
681 | * @see OPixmapProvider | ||
682 | */ | ||
683 | OPixmapProvider * pixmapProvider() const { return myPixProvider; } | ||
684 | |||
685 | /** | ||
686 | * Resets the current position of the up/down history. Call this | ||
687 | * when you manually call @ref setCurrentItem() or @ref clearEdit(). | ||
688 | */ | ||
689 | void reset() { slotReset(); } | ||
690 | |||
691 | public slots: | ||
692 | /** | ||
693 | * Adds an item to the end of the history list and to the completion list. | ||
694 | * If @ref maxCount() is reached, the first item of the list will be | ||
695 | * removed. | ||
696 | * | ||
697 | * If the last inserted item is the same as @p item, it will not be | ||
698 | * inserted again. | ||
699 | * | ||
700 | * If @ref duplicatesEnabled() is false, any equal existing item will be | ||
701 | * removed before @p item is added. | ||
702 | * | ||
703 | * Note: By using this method and not the Q and OComboBox insertItem() | ||
704 | * methods, you make sure that the combobox stays in sync with the | ||
705 | * completion. It would be annoying if completion would give an item | ||
706 | * not in the combobox, and vice versa. | ||
707 | * | ||
708 | * @see #removeFromHistory | ||
709 | * @see QComboBox::setDuplicatesEnabled | ||
710 | */ | ||
711 | void addToHistory( const QString& item ); | ||
712 | |||
713 | /** | ||
714 | * Clears the history and the completion list. | ||
715 | */ | ||
716 | void clearHistory(); | ||
717 | |||
718 | signals: | ||
719 | /** | ||
720 | * Emitted when the history was cleared by the entry in the popup menu. | ||
721 | */ | ||
722 | void cleared(); | ||
723 | |||
724 | protected: | ||
725 | /** | ||
726 | * Handling key-events, the shortcuts to rotate the items. | ||
727 | */ | ||
728 | virtual void keyPressEvent( QKeyEvent * ); | ||
729 | |||
730 | |||
731 | /** | ||
732 | * Inserts @p items into the combo, honouring @ref pixmapProvider() | ||
733 | * Does not update the completionObject. | ||
734 | * | ||
735 | * Note: @ref duplicatesEnabled() is not honored here. | ||
736 | * | ||
737 | * Called from @ref setHistoryItems() and @ref setPixmapProvider() | ||
738 | */ | ||
739 | void insertItems( const QStringList& items ); | ||
740 | |||
741 | /** | ||
742 | * @returns if we can modify the completion object or not. | ||
743 | */ | ||
744 | bool useCompletion() const { return compObj() != 0L; } | ||
745 | |||
746 | private slots: | ||
747 | /** | ||
748 | * Resets the iterate index to -1 | ||
749 | */ | ||
750 | void slotReset(); | ||
751 | |||
752 | /** | ||
753 | * Called from the popupmenu, | ||
754 | * calls clearHistory() and emits cleared() | ||
755 | */ | ||
756 | void slotClear(); | ||
757 | |||
758 | /** | ||
759 | * Appends our own context menu entry. | ||
760 | */ | ||
761 | void addContextMenuItems( QPopupMenu* ); | ||
762 | |||
763 | private: | ||
764 | void init( bool useCompletion ); | ||
765 | |||
766 | /** | ||
767 | * The current position (index) in the combobox, used for Up and Down | ||
768 | */ | ||
769 | int myIterateIndex; | ||
770 | |||
771 | /** | ||
772 | * The text typed before Up or Down was pressed. | ||
773 | */ | ||
774 | QString myText; | ||
775 | |||
776 | /** | ||
777 | * Indicates that the user at least once rotated Up through the entire list | ||
778 | * Needed to allow going back after rotation. | ||
779 | */ | ||
780 | bool myRotated; | ||
781 | OPixmapProvider *myPixProvider; | ||
782 | |||
783 | private: | ||
784 | class OHistoryComboPrivate; | ||
785 | OHistoryComboPrivate *d; | ||
786 | }; | ||
787 | |||
788 | |||
789 | #endif | ||
790 | |||