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

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