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 | */ |
47 | class 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 | |
53 | public: |
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 | |
184 | Q_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 | |
192 | protected: |
193 | virtual void mousePressEvent(QMouseEvent *event); |
194 | virtual void mouseMoveEvent(QMouseEvent *event); |
195 | |
196 | private: |
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 | |