Diffstat (limited to 'libopie2/qt3/opiecore/ocompletionbase.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | libopie2/qt3/opiecore/ocompletionbase.h | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/libopie2/qt3/opiecore/ocompletionbase.h b/libopie2/qt3/opiecore/ocompletionbase.h new file mode 100644 index 0000000..517667e --- a/dev/null +++ b/libopie2/qt3/opiecore/ocompletionbase.h | |||
@@ -0,0 +1,403 @@ | |||
1 | /* | ||
2 | This file is part of the Opie Project | ||
3 | |||
4 | Copyright (C) 2003 Michael Lauer <mickey@tm.informatik.uni-frankfurt.de> | ||
5 | Inspired by the KDE completion classes which are | ||
6 | Copyright (C) 2000 Dawit Alemayehu <adawit@kde.org> | ||
7 | =. | ||
8 | .=l. | ||
9 | .>+-= | ||
10 | _;:, .> :=|. This program is free software; you can | ||
11 | .> <`_, > . <= redistribute it and/or modify it under | ||
12 | :`=1 )Y*s>-.-- : the terms of the GNU Library General Public | ||
13 | .="- .-=="i, .._ License as published by the Free Software | ||
14 | - . .-<_> .<> Foundation; either version 2 of the License, | ||
15 | ._= =} : or (at your option) any later version. | ||
16 | .%`+i> _;_. | ||
17 | .i_,=:_. -<s. This program is distributed in the hope that | ||
18 | + . -:. = it will be useful, but WITHOUT ANY WARRANTY; | ||
19 | : .. .:, . . . without even the implied warranty of | ||
20 | =_ + =;=|` MERCHANTABILITY or FITNESS FOR A | ||
21 | _.=:. : :=>`: PARTICULAR PURPOSE. See the GNU | ||
22 | ..}^=.= = ; Library General Public License for more | ||
23 | ++= -. .` .: details. | ||
24 | : = ...= . :.=- | ||
25 | -. .:....=;==+<; You should have received a copy of the GNU | ||
26 | -_. . . )=. = Library General Public License along with | ||
27 | -- :-=` this library; see the file COPYING.LIB. | ||
28 | If not, write to the Free Software Foundation, | ||
29 | Inc., 59 Temple Place - Suite 330, | ||
30 | Boston, MA 02111-1307, USA. | ||
31 | */ | ||
32 | |||
33 | #ifndef OCOMPLETIONBASE_H | ||
34 | #define OCOMPLETIONBASE_H | ||
35 | |||
36 | /** | ||
37 | * An abstract base class for adding a completion feature | ||
38 | * into widgets. | ||
39 | * | ||
40 | * This is a convenience class that provides the basic functions | ||
41 | * needed to add text completion support into widgets. All that | ||
42 | * is required is an implementation for the pure virtual function | ||
43 | * @ref setCompletedText. Refer to @ref OLineEdit or @ref OComboBox | ||
44 | * to see how easily such support can be added using this as a base | ||
45 | * class. | ||
46 | * | ||
47 | * @short An abstract class for adding text completion support to widgets. | ||
48 | * @author Dawit Alemayehu <adawit@kde.org> | ||
49 | */ | ||
50 | |||
51 | class OCompletionBase | ||
52 | { | ||
53 | |||
54 | public: | ||
55 | |||
56 | /** | ||
57 | * Constants that represent the items whose short-cut | ||
58 | * key-binding is programmable. The default key-bindings | ||
59 | * for these items are defined in @ref OStdAccel. | ||
60 | */ | ||
61 | enum KeyBindingType { | ||
62 | /** | ||
63 | * Text completion (by default Ctrl-E). | ||
64 | */ | ||
65 | TextCompletion, | ||
66 | /** | ||
67 | * Switch to previous completion (by default Ctrl-Up). | ||
68 | */ | ||
69 | PrevCompletionMatch, | ||
70 | /** | ||
71 | * Switch to next completion (by default Ctrl-Down). | ||
72 | */ | ||
73 | NextCompletionMatch, | ||
74 | /** | ||
75 | * Substring completion (by default Ctrl-T). | ||
76 | */ | ||
77 | SubstringCompletion | ||
78 | }; | ||
79 | |||
80 | |||
81 | // Map for the key binding types mentioned above. | ||
82 | typedef QMap<KeyBindingType, OShortcut> KeyBindingMap; | ||
83 | |||
84 | /** | ||
85 | * Default constructor. | ||
86 | */ | ||
87 | OCompletionBase(); | ||
88 | |||
89 | /** | ||
90 | * Destructor. | ||
91 | */ | ||
92 | virtual ~OCompletionBase(); | ||
93 | |||
94 | /** | ||
95 | * Returns a pointer to the current completion object. | ||
96 | * | ||
97 | * If the object does not exist, it is automatically | ||
98 | * created. Note that the completion object created | ||
99 | * here is used by default to handle the signals | ||
100 | * internally. It is also deleted when this object's | ||
101 | * destructor is invoked. If you do not want these | ||
102 | * default settings, use @ref setAutoDeleteCompletionObject | ||
103 | * and @ref setHandleSignals to change the behavior. | ||
104 | * Alternatively, you can set the boolean parameter to | ||
105 | * false to disable the automatic handling of the signals | ||
106 | * by this object. Note that the boolean argument will be | ||
107 | * ignored if there already exists a completion object since | ||
108 | * no new object needs to be created. You need to use either | ||
109 | * @ref setHandleSignals or @ref setCompletionObject for | ||
110 | * such cases depending on your requirement. | ||
111 | * | ||
112 | * @param hsig if true, handles signals internally. | ||
113 | * @return a pointer the completion object. | ||
114 | */ | ||
115 | OCompletion* completionObject( bool hsig = true ); | ||
116 | |||
117 | /** | ||
118 | * Sets up the completion object to be used. | ||
119 | * | ||
120 | * This method assigns the completion object and sets it | ||
121 | * up to automatically handle the completion and rotation | ||
122 | * signals internally. You should use this function if | ||
123 | * you want to share one completion object among you widgets | ||
124 | * or need to use a customized completion object. | ||
125 | * | ||
126 | * The object assigned through this method is not deleted | ||
127 | * when this object's destructor is invoked unless you | ||
128 | * explicitly call @ref setAutoDeleteCompletionObject after | ||
129 | * calling this method. Also if you do not want the signals | ||
130 | * to be handled by an internal implementation, be sure to | ||
131 | * set the bool argument to false. | ||
132 | * | ||
133 | * This method is also called when a completion-object is created | ||
134 | * automatically, when completionObject() is called the first time. | ||
135 | * | ||
136 | * @param compObj a @ref OCompletion() or a derived child object. | ||
137 | * @param hsig if true, handles signals internally. | ||
138 | */ | ||
139 | virtual void setCompletionObject( OCompletion* /*compObj*/, bool hsig = true ); | ||
140 | |||
141 | /** | ||
142 | * Enables this object to handle completion and rotation | ||
143 | * events internally. | ||
144 | * | ||
145 | * This function simply assigns a boolean value that | ||
146 | * indicates whether it should handle rotation and | ||
147 | * completion events or not. Note that this does not | ||
148 | * stop the object from emitting signals when these | ||
149 | * events occur. | ||
150 | * | ||
151 | * @param handle if true, handle completion & rotation internally. | ||
152 | */ | ||
153 | virtual void setHandleSignals( bool /*handle*/ ); | ||
154 | |||
155 | /** | ||
156 | * Returns true if the completion object is deleted | ||
157 | * upon this widget's destruction. | ||
158 | * | ||
159 | * See @ref setCompletionObject() and @ref enableCompletion() | ||
160 | * for details. | ||
161 | * | ||
162 | * @return true if the completion object | ||
163 | */ | ||
164 | bool isCompletionObjectAutoDeleted() const { | ||
165 | return m_delegate ? m_delegate->isCompletionObjectAutoDeleted() : m_bAutoDelCompObj; | ||
166 | } | ||
167 | |||
168 | /** | ||
169 | * Sets the completion object when this widget's destructor | ||
170 | * is called. | ||
171 | * | ||
172 | * If the argument is set to true, the completion object | ||
173 | * is deleted when this widget's destructor is called. | ||
174 | * | ||
175 | * @param autoDelete if true, delete completion object on destruction. | ||
176 | */ | ||
177 | void setAutoDeleteCompletionObject( bool autoDelete ) { | ||
178 | if ( m_delegate ) | ||
179 | m_delegate->setAutoDeleteCompletionObject( autoDelete ); | ||
180 | else | ||
181 | m_bAutoDelCompObj = autoDelete; | ||
182 | } | ||
183 | |||
184 | /** | ||
185 | * Sets the widget's ability to emit text completion and | ||
186 | * rotation signals. | ||
187 | * | ||
188 | * Invoking this function with @p enable set to @p false will | ||
189 | * cause the completion & rotation signals not to be emitted. | ||
190 | * However, unlike setting the completion object to @p NULL | ||
191 | * using @ref setCompletionObject, disabling the emition of | ||
192 | * the signals through this method does not affect the current | ||
193 | * completion object. | ||
194 | * | ||
195 | * There is no need to invoke this function by default. When a | ||
196 | * completion object is created through @ref completionObject or | ||
197 | * @ref setCompletionObject, these signals are set to emit | ||
198 | * automatically. Also note that disabling this signals will not | ||
199 | * necessarily interfere with the objects ability to handle these | ||
200 | * events internally. See @ref setHandleSignals. | ||
201 | * | ||
202 | * @param enable if false, disables the emition of completion & rotation signals. | ||
203 | */ | ||
204 | void setEnableSignals( bool enable ) { | ||
205 | if ( m_delegate ) | ||
206 | m_delegate->setEnableSignals( enable ); | ||
207 | else | ||
208 | m_bEmitSignals = enable; | ||
209 | } | ||
210 | |||
211 | /** | ||
212 | * Returns true if the object handles the signals | ||
213 | * | ||
214 | * @return true if this signals are handled internally. | ||
215 | */ | ||
216 | bool handleSignals() const { return m_delegate ? m_delegate->handleSignals() : m_bHandleSignals; } | ||
217 | |||
218 | /** | ||
219 | * Returns true if the object emits the signals | ||
220 | * | ||
221 | * @return true if signals are emitted | ||
222 | */ | ||
223 | bool emitSignals() const { return m_delegate ? m_delegate->emitSignals() : m_bEmitSignals; } | ||
224 | |||
225 | /** | ||
226 | * Sets the type of completion to be used. | ||
227 | * | ||
228 | * The completion modes supported are those defined in | ||
229 | * @ref OGlobalSettings(). See below. | ||
230 | * | ||
231 | * @param mode Completion type: | ||
232 | * @li CompletionNone: Disables completion feature. | ||
233 | * @li CompletionAuto: Attempts to find a match & | ||
234 | * fills-in the remaining text. | ||
235 | * @li CompletionMan: Acts the same as the above | ||
236 | * except the action has to be | ||
237 | * manually triggered through | ||
238 | * pre-defined completion key. | ||
239 | * @li CompletionShell: Mimics the completion feature | ||
240 | * found in typical *nix shell | ||
241 | * environments. | ||
242 | * @li CompletionPopup: Shows all available completions at once, | ||
243 | * in a listbox popping up. | ||
244 | */ | ||
245 | virtual void setCompletionMode( OGlobalSettings::Completion mode ); | ||
246 | |||
247 | /** | ||
248 | * Returns the current completion mode. | ||
249 | * | ||
250 | * The return values are of type @ref OGlobalSettings::Completion. | ||
251 | * See @ref setCompletionMode() for details. | ||
252 | * | ||
253 | * @return the completion mode. | ||
254 | */ | ||
255 | OGlobalSettings::Completion completionMode() const { | ||
256 | return m_delegate ? m_delegate->completionMode() : m_iCompletionMode; | ||
257 | } | ||
258 | |||
259 | /** | ||
260 | * Sets the key-binding to be used for manual text | ||
261 | * completion, text rotation in a history list as | ||
262 | * well as a completion list. | ||
263 | * | ||
264 | * | ||
265 | * When the keys set by this function are pressed, a | ||
266 | * signal defined by the inheriting widget will be activated. | ||
267 | * If the default value or 0 is specified by the second | ||
268 | * parameter, then the key-binding as defined in the global | ||
269 | * setting should be used. This method returns false value | ||
270 | * for @p key is negative or the supplied key-binding conflicts | ||
271 | * with the ones set for one of the other features. | ||
272 | * | ||
273 | * NOTE: To use a modifier key (Shift, Ctrl, Alt) as part of | ||
274 | * the key-binding simply simply @p sum up the values of the | ||
275 | * modifier and the actual key. For example, to use CTRL+E as | ||
276 | * a key binding for one of the items, you would simply supply | ||
277 | * @p "Qt::CtrlButton + Qt::Key_E" as the second argument to this | ||
278 | * function. | ||
279 | * | ||
280 | * @param item the feature whose key-binding needs to be set: | ||
281 | * | ||
282 | * @li TextCompletionthe manual completion key-binding. | ||
283 | * @li PrevCompletionMatchthe previous match key for multiple completion. | ||
284 | * @li NextCompletionMatchthe next match key for for multiple completion. | ||
285 | * @li SubstringCompletion the key for substring completion | ||
286 | * | ||
287 | * @param key key-binding used to rotate down in a list. | ||
288 | * | ||
289 | * @return true if key-binding can successfully be set. | ||
290 | * @see #getKeyBinding | ||
291 | */ | ||
292 | bool setKeyBinding( KeyBindingType /*item*/ , const OShortcut& cut ); | ||
293 | |||
294 | /** | ||
295 | * Returns the key-binding used for the specified item. | ||
296 | * | ||
297 | * This methods returns the key-binding used to activate | ||
298 | * the feature feature given by @p item. If the binding | ||
299 | * contains modifier key(s), the SUM of the modifier key | ||
300 | * and the actual key code are returned. | ||
301 | * | ||
302 | * @return the key-binding used for the feature given by @p item. | ||
303 | * @see #setKeyBinding | ||
304 | */ | ||
305 | const OShortcut& getKeyBinding( KeyBindingType item ) const { | ||
306 | return m_delegate ? m_delegate->getKeyBinding( item ) : m_keyMap[ item ]; | ||
307 | } | ||
308 | |||
309 | /** | ||
310 | * Sets this object to use global values for key-bindings. | ||
311 | * | ||
312 | * This method changes the values of the key bindings for | ||
313 | * rotation and completion features to the default values | ||
314 | * provided in OGlobalSettings. | ||
315 | * | ||
316 | * NOTE: By default inheriting widgets should uses the | ||
317 | * global key-bindings so that there will be no need to | ||
318 | * call this method. | ||
319 | */ | ||
320 | void useGlobalKeyBindings(); | ||
321 | |||
322 | /** | ||
323 | * A pure virtual function that must be implemented by | ||
324 | * all inheriting classes. | ||
325 | * | ||
326 | * This function is intended to allow external completion | ||
327 | * implementations to set completed text appropriately. It | ||
328 | * is mostly relevant when the completion mode is set to | ||
329 | * CompletionAuto and CompletionManual modes. See | ||
330 | * @ref OCompletionBase::setCompletedText. | ||
331 | * Does nothing in CompletionPopup mode, as all available | ||
332 | * matches will be shown in the popup. | ||
333 | * | ||
334 | * @param text the completed text to be set in the widget. | ||
335 | */ | ||
336 | virtual void setCompletedText( const QString& text ) = 0; | ||
337 | |||
338 | /** | ||
339 | * A pure virtual function that must be implemented by | ||
340 | * all inheriting classes. | ||
341 | * | ||
342 | */ | ||
343 | virtual void setCompletedItems( const QStringList& items ) = 0; | ||
344 | |||
345 | /** | ||
346 | * Returns a pointer to the completion object. | ||
347 | * | ||
348 | * This method is only different from @ref completionObject() | ||
349 | * in that it does not create a new OCompletion object even if | ||
350 | * the internal pointer is @p NULL. Use this method to get the | ||
351 | * pointer to a completion object when inheriting so that you | ||
352 | * won't inadvertently create it!! | ||
353 | * | ||
354 | * @returns the completion object or NULL if one does not exist. | ||
355 | */ | ||
356 | OCompletion* compObj() const { return m_delegate ? m_delegate->compObj() : (OCompletion*) m_pCompObj; } | ||
357 | |||
358 | protected: | ||
359 | /** | ||
360 | * Returns a key-binding map | ||
361 | * | ||
362 | * This method is the same as @ref getKeyBinding() except it | ||
363 | * returns the whole keymap containing the key-bindings. | ||
364 | * | ||
365 | * @return the key-binding used for the feature given by @p item. | ||
366 | */ | ||
367 | KeyBindingMap getKeyBindings() const { return m_delegate ? m_delegate->getKeyBindings() : m_keyMap; } | ||
368 | |||
369 | void setDelegate( OCompletionBase *delegate ); | ||
370 | OCompletionBase *delegate() const { return m_delegate; } | ||
371 | |||
372 | private: | ||
373 | // This method simply sets the autodelete boolean for | ||
374 | // the completion object, the emit signals and handle | ||
375 | // signals internally flags to the provided values. | ||
376 | void setup( bool, bool, bool ); | ||
377 | |||
378 | // Flag that determined whether the completion object | ||
379 | // should be deleted when this object is destroyed. | ||
380 | bool m_bAutoDelCompObj; | ||
381 | // Determines whether this widget handles completion signals | ||
382 | // internally or not | ||
383 | bool m_bHandleSignals; | ||
384 | // Determines whether this widget fires rotation signals | ||
385 | bool m_bEmitSignals; | ||
386 | // Stores the completion mode locally. | ||
387 | OGlobalSettings::Completion m_iCompletionMode; | ||
388 | // Pointer to Completion object. | ||
389 | QGuardedPtr<OCompletion> m_pCompObj; | ||
390 | // Keybindings | ||
391 | KeyBindingMap m_keyMap; | ||
392 | // we may act as a proxy to another OCompletionBase object | ||
393 | OCompletionBase *m_delegate; | ||
394 | |||
395 | // FIXME: Revise this for Opie? | ||
396 | //protected: | ||
397 | // virtual void virtual_hook( int id, void* data ); | ||
398 | private: | ||
399 | OCompletionBasePrivate *d; | ||
400 | }; | ||
401 | |||
402 | #endif // OCOMPLETIONBASE_H | ||
403 | |||