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