1 | /* This file is part of the KDE libraries |
2 | |
3 | Copyright (c) 2000 Carsten Pfeiffer <pfeiffer@kde.org> |
4 | 2000 Stefan Schimanski <1Stein@gmx.de> |
5 | 2000,2001,2002,2003,2004 Dawit Alemayehu <adawit@kde.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License (LGPL) as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | |
23 | #ifndef KCOMPLETIONBOX_H |
24 | #define KCOMPLETIONBOX_H |
25 | |
26 | #include <klistwidget.h> |
27 | |
28 | class QEvent; |
29 | |
30 | /** |
31 | * @short A helper widget for "completion-widgets" (KLineEdit, KComboBox)) |
32 | * |
33 | * A little utility class for "completion-widgets", like KLineEdit or |
34 | * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without |
35 | * any window decoration, usually directly under the lineedit or combobox. |
36 | * It is filled with all possible matches for a completion, so the user |
37 | * can select the one he wants. |
38 | * |
39 | * It is used when KGlobalSettings::Completion == CompletionPopup or CompletionPopupAuto. |
40 | * |
41 | * @author Carsten Pfeiffer <pfeiffer@kde.org> |
42 | */ |
43 | class KDEUI_EXPORT KCompletionBox : public KListWidget |
44 | { |
45 | Q_OBJECT |
46 | Q_PROPERTY( bool isTabHandling READ isTabHandling WRITE setTabHandling ) |
47 | Q_PROPERTY(QString cancelledText READ cancelledText WRITE setCancelledText) |
48 | Q_PROPERTY( bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect ) |
49 | |
50 | public: |
51 | /** |
52 | * Constructs a KCompletionBox. |
53 | * |
54 | * The parent widget is used to give the focus back when pressing the |
55 | * up-button on the very first item. |
56 | */ |
57 | explicit KCompletionBox( QWidget *parent = 0 ); |
58 | |
59 | /** |
60 | * Destroys the box |
61 | */ |
62 | ~KCompletionBox(); |
63 | |
64 | virtual QSize sizeHint() const; |
65 | |
66 | /** |
67 | * @returns true if selecting an item results in the emition of the selected() signal. |
68 | */ |
69 | bool activateOnSelect() const; |
70 | |
71 | public Q_SLOTS: |
72 | /** |
73 | * Returns a list of all items currently in the box. |
74 | */ |
75 | QStringList items() const; |
76 | |
77 | /** |
78 | * Inserts @p items into the box. Does not clear the items before. |
79 | * @p index determines at which position @p items will be inserted. |
80 | * (defaults to appending them at the end) |
81 | */ |
82 | void insertItems( const QStringList& items, int index = -1 ); |
83 | |
84 | /** |
85 | * Clears the box and inserts @p items. |
86 | */ |
87 | void setItems( const QStringList& items ); |
88 | |
89 | /** |
90 | * Adjusts the size of the box to fit the width of the parent given in the |
91 | * constructor and pops it up at the most appropriate place, relative to |
92 | * the parent. |
93 | * |
94 | * Depending on the screensize and the position of the parent, this may |
95 | * be a different place, however the default is to pop it up and the |
96 | * lower left corner of the parent. |
97 | * |
98 | * Make sure to hide() the box when appropriate. |
99 | */ |
100 | virtual void (); |
101 | |
102 | /** |
103 | * Makes this widget (when visible) capture Tab-key events to traverse the |
104 | * items in the dropdown list (Tab goes down, Shift+Tab goes up). |
105 | * |
106 | * On by default, but should be turned off when used in combination with KUrlCompletion. |
107 | * When off, KLineEdit handles Tab itself, making it select the current item from the completion box, |
108 | * which is particularly useful when using KUrlCompletion. |
109 | * |
110 | * @see isTabHandling |
111 | */ |
112 | void setTabHandling( bool enable ); |
113 | |
114 | /** |
115 | * @returns true if this widget is handling Tab-key events to traverse the |
116 | * items in the dropdown list, otherwise false. |
117 | * |
118 | * Default is true. |
119 | * |
120 | * @see setTabHandling |
121 | */ |
122 | bool isTabHandling() const; |
123 | |
124 | /** |
125 | * Sets the text to be emitted if the user chooses not to |
126 | * pick from the available matches. |
127 | * |
128 | * If the canceled text is not set through this function, the |
129 | * userCancelled signal will not be emitted. |
130 | * |
131 | * @see userCancelled( const QString& ) |
132 | * @param txt the text to be emitted if the user cancels this box |
133 | */ |
134 | void setCancelledText( const QString& txt); |
135 | |
136 | /** |
137 | * @returns the text set via setCancelledText() or QString(). |
138 | */ |
139 | QString cancelledText() const; |
140 | |
141 | /** |
142 | * Set whether or not the selected signal should be emitted when an |
143 | * item is selected. By default the selected() signal is emitted. |
144 | * |
145 | * @param state false if the signal should not be emitted. |
146 | */ |
147 | void setActivateOnSelect(bool state); |
148 | |
149 | |
150 | /** |
151 | * Moves the selection one line down or select the first item if nothing is selected yet. |
152 | */ |
153 | void down(); |
154 | |
155 | /** |
156 | * Moves the selection one line up or select the first item if nothing is selected yet. |
157 | */ |
158 | void up(); |
159 | |
160 | /** |
161 | * Moves the selection one page down. |
162 | */ |
163 | void pageDown(); |
164 | |
165 | /** |
166 | * Moves the selection one page up. |
167 | */ |
168 | void pageUp(); |
169 | |
170 | /** |
171 | * Moves the selection up to the first item. |
172 | */ |
173 | void home(); |
174 | |
175 | /** |
176 | * Moves the selection down to the last item. |
177 | */ |
178 | void end(); |
179 | |
180 | /** |
181 | * Re-implemented for internal reasons. API is unaffected. |
182 | * Call it only if you really need it (i.e. the widget was hidden before) to have better performance. |
183 | */ |
184 | virtual void setVisible( bool visible ); |
185 | |
186 | Q_SIGNALS: |
187 | /** |
188 | * Emitted when an item was selected, contains the text of |
189 | * the selected item. |
190 | */ |
191 | void activated( const QString& ); |
192 | |
193 | /** |
194 | * Emitted whenever the user chooses to ignore the available |
195 | * selections and close the this box. |
196 | */ |
197 | void userCancelled( const QString& ); |
198 | |
199 | protected: |
200 | /** |
201 | * This calculates the size of the dropdown and the relative position of the top |
202 | * left corner with respect to the parent widget. This matches the geometry and position |
203 | * normally used by K/QComboBox when used with one. |
204 | */ |
205 | QRect calculateGeometry() const; |
206 | |
207 | /** |
208 | * This properly sizes and positions the listbox. |
209 | */ |
210 | void sizeAndPosition(); |
211 | |
212 | /** |
213 | * Reimplemented from KListWidget to get events from the viewport (to hide |
214 | * this widget on mouse-click, Escape-presses, etc. |
215 | */ |
216 | virtual bool eventFilter( QObject *, QEvent * ); |
217 | |
218 | /** |
219 | * The preferred global coordinate at which the completion box's top left corner |
220 | * should be positioned. |
221 | */ |
222 | virtual QPoint globalPositionHint() const; |
223 | |
224 | protected Q_SLOTS: |
225 | /** |
226 | * Called when an item was activated. Emits |
227 | * activated() with the item. |
228 | */ |
229 | virtual void slotActivated( QListWidgetItem * ); |
230 | |
231 | private Q_SLOTS: |
232 | void canceled(); |
233 | void slotItemClicked( QListWidgetItem * ); |
234 | |
235 | private: |
236 | class KCompletionBoxPrivate; |
237 | KCompletionBoxPrivate* const d; |
238 | }; |
239 | |
240 | |
241 | #endif // KCOMPLETIONBOX_H |
242 | |