1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Carsten Pfeiffer <pfeiffer@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2, as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef KURLCOMBOBOX_H
20#define KURLCOMBOBOX_H
21
22#include <kio/kio_export.h>
23
24#include <QtCore/QList>
25#include <QtCore/QMap>
26#include <QtCore/QStringList>
27#include <QtGui/QIcon>
28
29#include <kcombobox.h>
30#include <kurl.h>
31
32/**
33 * This combobox shows a number of recent URLs/directories, as well as some
34 * default directories.
35 * It will manage the default dirs root-directory, home-directory and
36 * Desktop-directory, as well as a number of URLs set via setUrls()
37 * and one additional entry to be set via setUrl().
38 *
39 * This widget forces the layout direction to be Qt::LeftToRight instead
40 * of inheriting the layout direction like a normal widget. This means
41 * that even in RTL desktops the widget will be displayed in LTR mode,
42 * as generally URLs are LTR by nature.
43 *
44 * @short A combo box showing a number of recent URLs/directories
45 * @author Carsten Pfeiffer <pfeiffer@kde.org>
46 */
47class KIO_EXPORT KUrlComboBox : public KComboBox
48{
49 Q_OBJECT
50 Q_PROPERTY(QStringList urls READ urls WRITE setUrls DESIGNABLE true)
51 Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems DESIGNABLE true)
52
53public:
54 /**
55 * This enum describes which kind of items is shown in the combo box.
56 */
57 enum Mode { Files = -1, Directories = 1, Both = 0 };
58 /**
59 * This Enumeration is used in setUrl() to determine which items
60 * will be removed when the given list is larger than maxItems().
61 *
62 * @li RemoveTop means that items will be removed from top
63 * @li RemoveBottom means, that items will be removed from the bottom
64 */
65 enum OverLoadResolving { RemoveTop, RemoveBottom };
66
67 /**
68 * Constructs a KUrlComboBox.
69 * @param mode is either Files, Directories or Both and controls the
70 * following behavior:
71 * @li Files all inserted URLs will be treated as files, therefore the
72 * url shown in the combo will never show a trailing /
73 * the icon will be the one associated with the file's mimetype.
74 * @li Directories all inserted URLs will be treated as directories, will
75 * have a trailing slash in the combobox. The current
76 * directory will show the "open folder" icon, other
77 * directories the "folder" icon.
78 * @li Both Don't mess with anything, just show the url as given.
79 * @param parent The parent object of this widget.
80 */
81 explicit KUrlComboBox(Mode mode, QWidget *parent = 0);
82 KUrlComboBox( Mode mode, bool rw, QWidget *parent=0);
83 /**
84 * Destructs the combo box.
85 */
86 ~KUrlComboBox();
87
88 /**
89 * Sets the current url. This combo handles exactly one url additionally
90 * to the default items and those set via setUrls(). So you can call
91 * setUrl() as often as you want, it will always replace the previous one
92 * set via setUrl().
93 * If @p url is already in the combo, the last item will stay there
94 * and the existing item becomes the current item.
95 * The current item will always have the open-directory-pixmap as icon.
96 *
97 * Note that you won't receive any signals, e.g. textChanged(),
98 * returnPressed() or activated() upon calling this method.
99 */
100 void setUrl( const KUrl& url );
101
102 /**
103 * Inserts @p urls into the combobox below the "default urls" (see
104 * addDefaultUrl).
105 *
106 * If the list of urls contains more items than maxItems, the first items
107 * will be stripped.
108 */
109 void setUrls( const QStringList &urls );
110
111 /**
112 * Inserts @p urls into the combobox below the "default urls" (see
113 * addDefaultUrl).
114 *
115 * If the list of urls contains more items than maxItems, the @p remove
116 * parameter determines whether the first or last items will be stripped.
117 */
118 void setUrls( const QStringList &urls, OverLoadResolving remove );
119
120 /**
121 * @returns a list of all urls currently handled. The list contains at most
122 * maxItems() items.
123 * Use this to save the list of urls in a config-file and reinsert them
124 * via setUrls() next time.
125 * Note that all default urls set via addDefaultUrl() are not
126 * returned, they will automatically be set via setUrls() or setUrl().
127 * You will always get fully qualified urls, i.e. with protocol like
128 * file:/
129 */
130 QStringList urls() const;
131
132 /**
133 * Sets how many items should be handled and displayed by the combobox.
134 * @see maxItems
135 */
136 void setMaxItems( int );
137
138 /**
139 * @returns the maximum of items the combobox handles.
140 * @see setMaxItems
141 */
142 int maxItems() const;
143
144 /**
145 * Adds a url that will always be shown in the combobox, it can't be
146 * "rotated away". Default urls won't be returned in urls() and don't
147 * have to be set via setUrls().
148 * If you want to specify a special pixmap, use the overloaded method with
149 * the pixmap parameter.
150 * Default URLs will be inserted into the combobox by setDefaults()
151 */
152 void addDefaultUrl( const KUrl& url, const QString& text = QString() );
153
154 /**
155 * Adds a url that will always be shown in the combobox, it can't be
156 * "rotated away". Default urls won't be returned in urls() and don't
157 * have to be set via setUrls().
158 * If you don't need to specify a pixmap, use the overloaded method without
159 * the pixmap parameter.
160 * Default URLs will be inserted into the combobox by setDefaults()
161 */
162 void addDefaultUrl( const KUrl& url, const QIcon& icon,
163 const QString& text = QString() );
164
165 /**
166 * Clears all items and inserts the default urls into the combo. Will be
167 * called implicitly upon the first call to setUrls() or setUrl()
168 * @see addDefaultUrl
169 */
170 void setDefaults();
171
172 /**
173 * Removes any occurrence of @p url. If @p checkDefaultUrls is false
174 * default-urls won't be removed.
175 */
176 void removeUrl( const KUrl& url, bool checkDefaultURLs = true );
177
178 /**
179 * Reimplemented from KComboBox (from KCompletion)
180 * @internal
181 */
182 virtual void setCompletionObject(KCompletion* compObj, bool hsig = true);
183
184Q_SIGNALS:
185 /**
186 * Emitted when an item was clicked at.
187 * @param url is the url of the now current item. If it is a local url,
188 * it won't have a protocol (file:/), otherwise it will.
189 */
190 void urlActivated( const KUrl& url );
191
192protected:
193 virtual void mousePressEvent(QMouseEvent *event);
194 virtual void mouseMoveEvent(QMouseEvent *event);
195
196private:
197 class KUrlComboBoxPrivate;
198 KUrlComboBoxPrivate* const d;
199
200 Q_DISABLE_COPY(KUrlComboBox)
201
202 Q_PRIVATE_SLOT( d, void _k_slotActivated( int ) )
203};
204
205
206#endif // KURLCOMBOBOX_H
207