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
28class 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 */
43class 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
50public:
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
71public 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 popup();
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
186Q_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
199protected:
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
224protected Q_SLOTS:
225 /**
226 * Called when an item was activated. Emits
227 * activated() with the item.
228 */
229 virtual void slotActivated( QListWidgetItem * );
230
231private Q_SLOTS:
232 void canceled();
233 void slotItemClicked( QListWidgetItem * );
234
235private:
236 class KCompletionBoxPrivate;
237 KCompletionBoxPrivate* const d;
238};
239
240
241#endif // KCOMPLETIONBOX_H
242