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/olineedit.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/olineedit.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | libopie2/qt3/opieui/olineedit.h | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/libopie2/qt3/opieui/olineedit.h b/libopie2/qt3/opieui/olineedit.h new file mode 100644 index 0000000..ecfca27 --- a/dev/null +++ b/libopie2/qt3/opieui/olineedit.h | |||
@@ -0,0 +1,498 @@ | |||
1 | /* | ||
2 | This file Copyright (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de> | ||
3 | is part of the Copyright (C) 2001 Carsten Pfeiffer <pfeiffer@kde.org>, Dawit Alemayehu <adawit@kde.org> | ||
4 | Opie Project Copyright (C) 1999 Preston Brown <pbrown@kde.org>, Patrick Ward <PAT_WARD@HP-USA-om5.om.hp.com> | ||
5 | Copyright (C) 1997 Sven Radej (sven.radej@iname.com) | ||
6 | =. | ||
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 OLINEEDIT_H | ||
34 | #define OLINEEDIT_H | ||
35 | |||
36 | /* QT */ | ||
37 | |||
38 | #include <qlineedit.h> | ||
39 | |||
40 | /* OPIE */ | ||
41 | |||
42 | #include <opie2/ocompletion.h> | ||
43 | #include <opie2/ocompletionbase.h> | ||
44 | |||
45 | class QPopupMenu; | ||
46 | |||
47 | class OCompletionBox; | ||
48 | typedef QString KURL; //class KURL; | ||
49 | |||
50 | /** | ||
51 | * An enhanced QLineEdit widget for inputting text. | ||
52 | * | ||
53 | * @sect Detail | ||
54 | * | ||
55 | * This widget inherits from @ref QLineEdit and implements the following | ||
56 | * additional functionalities: q completion object that provides both | ||
57 | * automatic and manual text completion as well as multiple match iteration | ||
58 | * features, configurable key-bindings to activate these features and a | ||
59 | * popup-menu item that can be used to allow the user to set text completion | ||
60 | * modes on the fly based on their preference. | ||
61 | * | ||
62 | * To support these new features OLineEdit also emits a few more | ||
63 | * additional signals. These are: @ref completion( const QString& ), | ||
64 | * textRotation( KeyBindingType ), and @ref returnPressed( const QString& ). | ||
65 | * The completion signal can be connected to a slot that will assist the | ||
66 | * user in filling out the remaining text. The text rotation signal is | ||
67 | * intended to be used to iterate through the list of all possible matches | ||
68 | * whenever there is more than one match for the entered text. The | ||
69 | * @p returnPressed( const QString& ) signals are the same as QLineEdit's | ||
70 | * except it provides the current text in the widget as its argument whenever | ||
71 | * appropriate. | ||
72 | * | ||
73 | * This widget by default creates a completion object when you invoke | ||
74 | * the @ref completionObject( bool ) member function for the first time or | ||
75 | * use @ref setCompletionObject( OCompletion*, bool ) to assign your own | ||
76 | * completion object. Additionally, to make this widget more functional, | ||
77 | * OLineEdit will by default handle the text rotation and completion | ||
78 | * events internally when a completion object is created through either one | ||
79 | * of the methods mentioned above. If you do not need this functionality, | ||
80 | * simply use @ref OCompletionBase::setHandleSignals( bool ) or set the | ||
81 | * boolean parameter in the above functions to FALSE. | ||
82 | * | ||
83 | * The default key-bindings for completion and rotation is determined | ||
84 | * from the global settings in @ref OStdAccel. These values, however, | ||
85 | * can be overriden locally by invoking @ref OCompletionBase::setKeyBinding(). | ||
86 | * The values can easily be reverted back to the default setting, by simply | ||
87 | * calling @ref useGlobalSettings(). An alternate method would be to default | ||
88 | * individual key-bindings by usning @ref setKeyBinding() with the default | ||
89 | * second argument. | ||
90 | * | ||
91 | * NOTE that if the @p EchoMode for this widget is set to something other | ||
92 | * than @p QLineEdit::Normal, the completion mode will always be defaulted | ||
93 | * to @ref PGlobalSettings::CompletionNone. This is done purposefully to guard | ||
94 | * against protected entries such as passwords being cached in @ref OCompletion's | ||
95 | * list. Hence, if the @p EchoMode is not @ref QLineEdit::Normal, the completion | ||
96 | * mode is automatically disabled. | ||
97 | * | ||
98 | * @sect Useage | ||
99 | * | ||
100 | * To enable the basic completion feature : | ||
101 | * | ||
102 | * <pre> | ||
103 | * OLineEdit *edit = new OLineEdit( this, "mywidget" ); | ||
104 | * OCompletion *comp = edit->completionObject(); | ||
105 | * // Fill the completion object with a list of possible matches | ||
106 | * QStringList list; | ||
107 | * list << "mickeyl@handhelds.org" << "mickey@tm.informatik.uni-frankfurt.de>" << "mickey@Vanille.de"; | ||
108 | * comp->setItems( list ); | ||
109 | * // Connect to the return pressed signal (optional) | ||
110 | * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)); | ||
111 | * </pre> | ||
112 | * | ||
113 | * To use a customized completion objects or your | ||
114 | * own completion object : | ||
115 | * | ||
116 | * <pre> | ||
117 | * OLineEdit *edit = new OLineEdit( this,"mywidget" ); | ||
118 | * KURLCompletion *comp = new KURLCompletion(); | ||
119 | * edit->setCompletionObject( comp ); | ||
120 | * // Connect to the return pressed signal - optional | ||
121 | * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)); | ||
122 | * </pre> | ||
123 | * | ||
124 | * Note that you have to either delete the allocated completion object | ||
125 | * when you don't need it anymore, or call | ||
126 | * setAutoDeleteCompletionObject( true ); | ||
127 | * | ||
128 | * @sect Miscellaneous function calls : | ||
129 | * | ||
130 | * <pre> | ||
131 | * // Tell the widget not to handle completion and | ||
132 | * // iteration internally. | ||
133 | * edit->setHandleSignals( false ); | ||
134 | * // Set your own completion key for manual completions. | ||
135 | * edit->setKeyBinding( OCompletionBase::TextCompletion, Qt::End ); | ||
136 | * // Hide the context (popup) menu | ||
137 | * edit->setContextMenuEnabled( false ); | ||
138 | * // Temporarly disable signal emitions | ||
139 | * // (both completion & iteration signals) | ||
140 | * edit->disableSignals(); | ||
141 | * // Default the key-bindings to system settings. | ||
142 | * edit->useGlobalKeyBindings(); | ||
143 | * </pre> | ||
144 | * | ||
145 | * @short An enhanced single line input widget. | ||
146 | * @author Dawit Alemayehu <adawit@kde.org> | ||
147 | * @author Opie adaption by Michael Lauer <mickey@tm.informatik.uni-frankfurt.de> | ||
148 | */ | ||
149 | |||
150 | class OLineEdit : public QLineEdit, public OCompletionBase | ||
151 | { | ||
152 | friend class OComboBox; | ||
153 | |||
154 | Q_OBJECT | ||
155 | Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled ) | ||
156 | Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled ) | ||
157 | |||
158 | public: | ||
159 | |||
160 | /** | ||
161 | * Constructs a OLineEdit object with a default text, a parent, | ||
162 | * and a name. | ||
163 | * | ||
164 | * @param string Text to be shown in the edit widget. | ||
165 | * @param parent The parent object of this widget. | ||
166 | * @param name the name of this widget | ||
167 | */ | ||
168 | OLineEdit( const QString &string, QWidget *parent, const char *name = 0 ); | ||
169 | |||
170 | /** | ||
171 | * Constructs a OLineEdit object with a parent and a name. | ||
172 | * | ||
173 | * @param string Text to be shown in the edit widget. | ||
174 | * @param parent The parent object of this widget. | ||
175 | * @param name The name of this widget. | ||
176 | */ | ||
177 | OLineEdit ( QWidget *parent=0, const char *name=0 ); | ||
178 | |||
179 | /** | ||
180 | * Destructor. | ||
181 | */ | ||
182 | virtual ~OLineEdit (); | ||
183 | |||
184 | /** | ||
185 | * Sets @p url into the lineedit. It uses @ref KURL::prettyURL() so | ||
186 | * that the url is properly decoded for displaying. | ||
187 | */ | ||
188 | void setURL( const KURL& url ); | ||
189 | |||
190 | /** | ||
191 | * Puts the text cursor at the end of the string. | ||
192 | * | ||
193 | * This method is deprecated. Use @ref QLineEdit::end() | ||
194 | * instead. | ||
195 | * | ||
196 | * @deprecated | ||
197 | * @ref QLineEdit::end() | ||
198 | */ | ||
199 | void cursorAtEnd() { end( false ); } | ||
200 | |||
201 | /** | ||
202 | * Re-implemented from @ref OCompletionBase for internal reasons. | ||
203 | * | ||
204 | * This function is re-implemented in order to make sure that | ||
205 | * the EchoMode is acceptable before we set the completion mode. | ||
206 | * | ||
207 | * See @ref OCompletionBase::setCompletionMode | ||
208 | */ | ||
209 | virtual void setCompletionMode( OGlobalSettings::Completion mode ); | ||
210 | |||
211 | /** | ||
212 | * Enables/disables the popup (context) menu. | ||
213 | * | ||
214 | * Note that when this function is invoked with its argument | ||
215 | * set to @p true, then both the context menu and the completion | ||
216 | * menu item are enabled. If you do not want to the completion | ||
217 | * item to be visible simply invoke @ref hideModechanger() right | ||
218 | * after calling this method. Also by default, the context | ||
219 | * menu is automatically created if this widget is editable. Thus | ||
220 | * you need to call this function with the argument set to false | ||
221 | * if you do not want this behaviour. | ||
222 | * | ||
223 | * @param showMenu If @p true, show the context menu. | ||
224 | */ | ||
225 | virtual void setContextMenuEnabled( bool showMenu ) { m_bEnableMenu = showMenu; } | ||
226 | |||
227 | /** | ||
228 | * Returns @p true when the context menu is enabled. | ||
229 | */ | ||
230 | bool isContextMenuEnabled() const { return m_bEnableMenu; } | ||
231 | |||
232 | /** | ||
233 | * Enables/Disables handling of URL drops. If enabled and the user | ||
234 | * drops an URL, the decoded URL will be inserted. Otherwise the default | ||
235 | * behaviour of QLineEdit is used, which inserts the encoded URL. | ||
236 | * | ||
237 | * @param enable If @p true, insert decoded URLs | ||
238 | */ | ||
239 | void setURLDropsEnabled( bool enable ); | ||
240 | |||
241 | /** | ||
242 | * Returns @p true when decoded URL drops are enabled | ||
243 | */ | ||
244 | bool isURLDropsEnabled() const; | ||
245 | |||
246 | /** | ||
247 | * By default, OLineEdit recognizes @p Key_Return and @p Key_Enter and emits | ||
248 | * the @ref returnPressed() signals, but it also lets the event pass, | ||
249 | * for example causing a dialog's default-button to be called. | ||
250 | * | ||
251 | * Call this method with @p trap = @p true to make @p OLineEdit stop these | ||
252 | * events. The signals will still be emitted of course. | ||
253 | * | ||
254 | * @see trapReturnKey() | ||
255 | */ | ||
256 | void setTrapReturnKey( bool trap ); | ||
257 | |||
258 | /** | ||
259 | * @returns @p true if keyevents of @p Key_Return or | ||
260 | * @p Key_Enter will be stopped or if they will be propagated. | ||
261 | * | ||
262 | * @see setTrapReturnKey () | ||
263 | */ | ||
264 | bool trapReturnKey() const; | ||
265 | |||
266 | /** | ||
267 | * Re-implemented for internal reasons. API not affected. | ||
268 | * | ||
269 | * @reimplemented | ||
270 | */ | ||
271 | virtual bool eventFilter( QObject *, QEvent * ); | ||
272 | |||
273 | /** | ||
274 | * @returns the completion-box, that is used in completion mode | ||
275 | * @ref KGlobalSettings::CompletionPopup. | ||
276 | * This method will create a completion-box if none is there, yet. | ||
277 | * | ||
278 | * @param create Set this to false if you don't want the box to be created | ||
279 | * i.e. to test if it is available. | ||
280 | */ | ||
281 | OCompletionBox * completionBox( bool create = true ); | ||
282 | |||
283 | /** | ||
284 | * Reimplemented for internal reasons, the API is not affected. | ||
285 | */ | ||
286 | virtual void setCompletionObject( OCompletion *, bool hsig = true ); | ||
287 | |||
288 | |||
289 | signals: | ||
290 | |||
291 | /** | ||
292 | * Emitted when the user presses the return key. | ||
293 | * | ||
294 | * The argument is the current text. Note that this | ||
295 | * signal is @em not emitted if the widget's @p EchoMode is set to | ||
296 | * @ref QLineEdit::EchoMode. | ||
297 | */ | ||
298 | void returnPressed( const QString& ); | ||
299 | |||
300 | /** | ||
301 | * Emitted when the completion key is pressed. | ||
302 | * | ||
303 | * Please note that this signal is @em not emitted if the | ||
304 | * completion mode is set to @p CompletionNone or @p EchoMode is | ||
305 | * @em normal. | ||
306 | */ | ||
307 | void completion( const QString& ); | ||
308 | |||
309 | /** | ||
310 | * Emitted when the shortcut for substring completion is pressed. | ||
311 | */ | ||
312 | void substringCompletion( const QString& ); | ||
313 | |||
314 | /** | ||
315 | * Emitted when the text rotation key-bindings are pressed. | ||
316 | * | ||
317 | * The argument indicates which key-binding was pressed. | ||
318 | * In OLineEdit's case this can be either one of two values: | ||
319 | * @ref PrevCompletionMatch or @ref NextCompletionMatch. See | ||
320 | * @ref OCompletionBase::setKeyBinding for details. | ||
321 | * | ||
322 | * Note that this signal is @em not emitted if the completion | ||
323 | * mode is set to @p KGlobalSettings::CompletionNone or @p echoMode() is @em not normal. | ||
324 | */ | ||
325 | void textRotation( OCompletionBase::KeyBindingType ); | ||
326 | |||
327 | /** | ||
328 | * Emitted when the user changed the completion mode by using the | ||
329 | * popupmenu. | ||
330 | */ | ||
331 | void completionModeChanged( OGlobalSettings::Completion ); | ||
332 | |||
333 | /** | ||
334 | * Emitted before the context menu is displayed. | ||
335 | * | ||
336 | * The signal allows you to add your own entries into the | ||
337 | * the context menu that is created on demand. | ||
338 | * | ||
339 | * NOTE: Do not store the pointer to the QPopupMenu | ||
340 | * provided through since it is created and deleted | ||
341 | * on demand. | ||
342 | * | ||
343 | * @param the context menu about to be displayed | ||
344 | */ | ||
345 | void aboutToShowContextMenu( QPopupMenu* ); | ||
346 | |||
347 | public slots: | ||
348 | |||
349 | /** | ||
350 | * Re-implemented for internal reasons. API not changed. | ||
351 | */ | ||
352 | virtual void setReadOnly(bool); | ||
353 | |||
354 | /** | ||
355 | * Iterates through all possible matches of the completed text or | ||
356 | * the history list. | ||
357 | * | ||
358 | * This function simply iterates over all possible matches in case | ||
359 | * multimple matches are found as a result of a text completion request. | ||
360 | * It will have no effect if only a single match is found. | ||
361 | * | ||
362 | * @param type The key-binding invoked. | ||
363 | */ | ||
364 | void rotateText( OCompletionBase::KeyBindingType /* type */ ); | ||
365 | |||
366 | /** | ||
367 | * See @ref OCompletionBase::setCompletedText. | ||
368 | */ | ||
369 | virtual void setCompletedText( const QString& ); | ||
370 | |||
371 | /** | ||
372 | * Sets @p items into the completion-box if @ref completionMode() is | ||
373 | * CompletionPopup. The popup will be shown immediately. | ||
374 | */ | ||
375 | void setCompletedItems( const QStringList& items ); | ||
376 | |||
377 | /** | ||
378 | * Reimplemented to workaround a buggy QLineEdit::clear() | ||
379 | * (changing the clipboard to the text we just had in the lineedit) | ||
380 | */ | ||
381 | virtual void clear(); | ||
382 | |||
383 | protected slots: | ||
384 | |||
385 | /** | ||
386 | * Completes the remaining text with a matching one from | ||
387 | * a given list. | ||
388 | */ | ||
389 | virtual void makeCompletion( const QString& ); | ||
390 | |||
391 | /** | ||
392 | * @deprecated. Will be removed in the next major release! | ||
393 | */ | ||
394 | void slotAboutToShow() {} | ||
395 | |||
396 | /** | ||
397 | * @deprecated. Will be removed in the next major release! | ||
398 | */ | ||
399 | void slotCancelled() {} | ||
400 | |||
401 | protected: | ||
402 | |||
403 | /** | ||
404 | * Re-implemented for internal reasons. API not affected. | ||
405 | * | ||
406 | * See @ref QLineEdit::keyPressEvent(). | ||
407 | */ | ||
408 | virtual void keyPressEvent( QKeyEvent * ); | ||
409 | |||
410 | /** | ||
411 | * Re-implemented for internal reasons. API not affected. | ||
412 | * | ||
413 | * See @ref QLineEdit::mousePressEvent(). | ||
414 | */ | ||
415 | virtual void mousePressEvent( QMouseEvent * ); | ||
416 | |||
417 | /** | ||
418 | * Re-implemented for internal reasons. API not affected. | ||
419 | * | ||
420 | * See @ref QWidget::mouseDoubleClickEvent(). | ||
421 | */ | ||
422 | virtual void mouseDoubleClickEvent( QMouseEvent * ); | ||
423 | |||
424 | /** | ||
425 | * Re-implemented for internal reasons. API not affected. | ||
426 | * | ||
427 | * See @ref QLineEdit::createPopupMenu(). | ||
428 | */ | ||
429 | virtual QPopupMenu *createPopupMenu(); | ||
430 | |||
431 | /** | ||
432 | * Re-implemented to handle URI drops. | ||
433 | * | ||
434 | * See @ref QLineEdit::dropEvent(). | ||
435 | */ | ||
436 | //virtual void dropEvent( QDropEvent * ); | ||
437 | |||
438 | /* | ||
439 | * This function simply sets the lineedit text and | ||
440 | * highlights the text appropriately if the boolean | ||
441 | * value is set to true. | ||
442 | * | ||
443 | * @param text | ||
444 | * @param marked | ||
445 | */ | ||
446 | virtual void setCompletedText( const QString& /*text*/, bool /*marked*/ ); | ||
447 | |||
448 | /** | ||
449 | * Reimplemented for internal reasons, the API is not affected. | ||
450 | */ | ||
451 | virtual void create( WId = 0, bool initializeWindow = true, | ||
452 | bool destroyOldWindow = true ); | ||
453 | |||
454 | private slots: | ||
455 | void completionMenuActivated( int id ); | ||
456 | void tripleClickTimeout(); // resets possibleTripleClick | ||
457 | |||
458 | private: | ||
459 | // Constants that represent the ID's of the popup menu. | ||
460 | // TODO: See if we can replace this mess with KActionMenu | ||
461 | // in the future though it's working lovely. | ||
462 | enum MenuID { | ||
463 | Default = 42, | ||
464 | NoCompletion, | ||
465 | AutoCompletion, | ||
466 | ShellCompletion, | ||
467 | PopupCompletion, | ||
468 | SemiAutoCompletion | ||
469 | }; | ||
470 | |||
471 | /** | ||
472 | * Initializes variables. Called from the constructors. | ||
473 | */ | ||
474 | void init(); | ||
475 | |||
476 | /** | ||
477 | * Creates the completion box | ||
478 | */ | ||
479 | void makeCompletionBox(); | ||
480 | |||
481 | /** | ||
482 | * Checks whether we should/should not consume a key used as | ||
483 | * an accelerator. | ||
484 | */ | ||
485 | //bool overrideAccel (const QKeyEvent* e); | ||
486 | |||
487 | bool m_bEnableMenu; | ||
488 | |||
489 | bool possibleTripleClick; // set in mousePressEvent, deleted in tripleClickTimeout | ||
490 | |||
491 | protected: | ||
492 | //virtual void virtual_hook( int id, void* data ); | ||
493 | private: | ||
494 | class OLineEditPrivate; | ||
495 | OLineEditPrivate *d; | ||
496 | }; | ||
497 | |||
498 | #endif | ||