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
22class QUrl;
23class 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 */
41class 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
54public:
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
206Q_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
214protected:
215 void mousePressEvent(QMouseEvent *event) override;
216 void mouseMoveEvent(QMouseEvent *event) override;
217
218private:
219 friend class KUrlComboBoxPrivate;
220 std::unique_ptr<KUrlComboBoxPrivate> const d;
221
222 Q_DISABLE_COPY(KUrlComboBox)
223};
224
225#endif // KURLCOMBOBOX_H
226

source code of kio/src/widgets/kurlcombobox.h