KIO

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

KDE's Doxygen guidelines are available online.