KIO

kurlcombobox.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <[email protected]>
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 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 <[email protected]>
41  */
42 class 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 
48 public:
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 
178 Q_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 
185 protected:
186  void mousePressEvent(QMouseEvent *event) override;
187  void mouseMoveEvent(QMouseEvent *event) override;
188 
189 private:
190  friend class KUrlComboBoxPrivate;
191  std::unique_ptr<KUrlComboBoxPrivate> const d;
192 
194 
195  Q_PRIVATE_SLOT(d, void _k_slotActivated(int))
196 };
197 
198 #endif // KURLCOMBOBOX_H
Q_PROPERTY(...)
A combo box showing a number of recent URLs/directories.
Definition: kurlcombobox.h:42
virtual void mousePressEvent(QMouseEvent *e) override
virtual void setCompletionObject(KCompletion *completionObject, bool handleSignals=true)
Q_SIGNALSQ_SIGNALS
OverLoadResolving
This Enumeration is used in setUrl() to determine which items will be removed when the given list is ...
Definition: kurlcombobox.h:60
Mode
This enum describes which kind of items is shown in the combo box.
Definition: kurlcombobox.h:52
virtual void mouseMoveEvent(QMouseEvent *event)
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 9 2022 03:53:38 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.