summaryrefslogtreecommitdiffstats
path: root/kdeui/kcompletionbox.h
blob: 2b536d172f7f54613b305859de4f12d9c526542c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
/* This file is part of the KDE libraries

   Copyright (c) 2000 Carsten Pfeiffer <pfeiffer@kde.org>
                 2000 Stefan Schimanski <1Stein@gmx.de>
                 2000,2001,2002,2003,2004 Dawit Alemayehu <adawit@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License (LGPL) as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef KCOMPLETIONBOX_H
#define KCOMPLETIONBOX_H

class QEvent;
#include <tqstringlist.h>
#include <klistbox.h>

/**
 * @short A helper widget for "completion-widgets" (KLineEdit, KComboBox))
 *
 * A little utility class for "completion-widgets", like KLineEdit or
 * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without
 * any window decoration, usually directly under the lineedit or combobox.
 * It is filled with all possible matches for a completion, so the user
 * can select the one he wants.
 *
 * It is used when KGlobalSettings::Completion == CompletionPopup or CompletionPopupAuto.
 *
 * @author Carsten Pfeiffer <pfeiffer@kde.org>
 */
class KDEUI_EXPORT KCompletionBox : public KListBox
{
    Q_OBJECT
    Q_PROPERTY( bool isTabHandling READ isTabHandling WRITE setTabHandling )
    Q_PROPERTY(TQString cancelledText READ cancelledText WRITE setCancelledText)
    Q_PROPERTY( bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect )

public:
    /**
     * Constructs a KCompletionBox.
     *
     * The parent widget is used to give the focus back when pressing the
     * up-button on the very first item.
     */
    KCompletionBox( TQWidget *parent, const char *name = 0 );

    /**
     * Destroys the box
     */
    ~KCompletionBox();

    virtual TQSize sizeHint() const;

    /**
     * @returns true if selecting an item results in the emition of the selected signal.
     *
     * @since 3.4.1
     */
    bool activateOnSelect() const;

public slots:
    /**
     * Returns a list of all items currently in the box.
     */
    TQStringList items() const;

    /**
     * Inserts @p items into the box. Does not clear the items before.
     * @p index determines at which position @p items will be inserted.
     * (defaults to appending them at the end)
     */
    void insertItems( const TQStringList& items, int index = -1 );

    /**
     * Clears the box and inserts @p items.
     */
    void setItems( const TQStringList& items );

    /**
     * Adjusts the size of the box to fit the width of the parent given in the
     * constructor and pops it up at the most appropriate place, relative to
     * the parent.
     *
     * Depending on the screensize and the position of the parent, this may
     * be a different place, however the default is to pop it up and the
     * lower left corner of the parent.
     *
     * Make sure to hide() the box when appropriate.
     */
    virtual void popup();

    /**
     * Makes this widget (when visible) capture Tab-key events to traverse the
     * items in the dropdown list.
     *
     * Default off, as it conflicts with the usual behavior of Tab to traverse
     * widgets. It is useful for cases like Konqueror's Location Bar, though.
     *
     * @see isTabHandling
     */
    void setTabHandling( bool enable );

    /**
     * @returns true if this widget is handling Tab-key events to traverse the
     * items in the dropdown list, otherwise false.
     *
     * Default is false.
     *
     * @see setTabHandling
     */
    bool isTabHandling() const;

    /**
     * Sets the text to be emitted if the user chooses not to
     * pick from the available matches.
     *
     * If the canceled text is not set through this function, the
     * userCancelled signal will not be emitted.
     *
     * @see userCancelled( const TQString& )
     * @param txt  the text to be emitted if the user cancels this box
     */
    void setCancelledText( const TQString& txt);

    /**
     * @returns the text set via setCancelledText() or TQString::null.
     */
    TQString cancelledText() const;

    /**
     * Set whether or not the selected signal should be emitted when an
     * item is selected. By default the selected signal is emitted.
     *
     * @param state false if the signal should not be emitted.
     * @since 3.4.1
     */
    void setActivateOnSelect(bool state);


    /**
     * Moves the selection one line down or select the first item if nothing is selected yet.
     */
    void down();

    /**
     * Moves the selection one line up or select the first item if nothing is selected yet.
     */
    void up();

    /**
     * Moves the selection one page down.
     */
    void pageDown();

    /**
     * Moves the selection one page up.
     */
    void pageUp();

    /**
     * Moves the selection up to the first item.
     */
    void home();

    /**
     * Moves the selection down to the last item.
     */
    void end();

    /**
     * Re-implemented for internal reasons.  API is unaffected.
     */
    virtual void show();

    /**
     * Re-implemented for internal reasons.  API is unaffected.
     */
    virtual void hide();

signals:
    /**
     * Emitted when an item was selected, contains the text of
     * the selected item.
     */
    void activated( const TQString& );

    /**
     * Emitted whenever the user chooses to ignore the available
     * selections and close the this box.
     */
    void userCancelled( const TQString& );

protected:
    /**
     * This calculates the size of the dropdown and the relative position of the top
     * left corner with respect to the parent widget. This matches the geometry and position
     * normally used by K/TQComboBox when used with one.
     */
    TQRect calculateGeometry() const;

    /**
     * This properly sizes and positions the listbox.
     */
    void sizeAndPosition();

    /**
     * Reimplemented from KListBox to get events from the viewport (to hide
     * this widget on mouse-click, Escape-presses, etc.
     */
    virtual bool eventFilter( TQObject *, TQEvent * );

protected slots:
    /**
     * Called when an item was activated. Emits
     * activated() with the item.
     */
    virtual void slotActivated( TQListBoxItem * );

private slots:
    void slotSetCurrentItem( TQListBoxItem *i ) { setCurrentItem( i ); } // grrr
    void slotCurrentChanged();
    void canceled();
    void slotItemClicked( TQListBoxItem * );

protected:
    virtual void virtual_hook( int id, void* data );

private:
    class KCompletionBoxPrivate;
    KCompletionBoxPrivate* const d;
};


#endif // KCOMPLETIONBOX_H