File indexing completed on 2024-11-10 12:24:05
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 0008 #ifndef KURLCOMBOBOX_H 0009 #define KURLCOMBOBOX_H 0010 0011 #include "kiowidgets_export.h" 0012 0013 #include <QIcon> 0014 #include <QList> 0015 #include <QMap> 0016 #include <QStringList> 0017 0018 #include <KComboBox> 0019 0020 #include <memory> 0021 0022 class QUrl; 0023 class KUrlComboBoxPrivate; 0024 0025 /** 0026 * @class KUrlComboBox kurlcombobox.h <KUrlComboBox> 0027 * 0028 * This combobox shows a number of recent URLs/directories, as well as some 0029 * default directories. 0030 * It will manage the default dirs root-directory, home-directory and 0031 * Desktop-directory, as well as a number of URLs set via setUrls() 0032 * and one additional entry to be set via setUrl(). 0033 * 0034 * This widget forces the layout direction to be Qt::LeftToRight instead 0035 * of inheriting the layout direction like a normal widget. This means 0036 * that even in RTL desktops the widget will be displayed in LTR mode, 0037 * as generally URLs are LTR by nature. 0038 * 0039 * @short A combo box showing a number of recent URLs/directories 0040 * @author Carsten Pfeiffer <pfeiffer@kde.org> 0041 */ 0042 class KIOWIDGETS_EXPORT KUrlComboBox : public KComboBox 0043 { 0044 Q_OBJECT 0045 Q_PROPERTY(QStringList urls READ urls WRITE setUrls DESIGNABLE true) 0046 Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems DESIGNABLE true) 0047 0048 public: 0049 /** 0050 * This enum describes which kind of items is shown in the combo box. 0051 */ 0052 enum Mode { Files = -1, Directories = 1, Both = 0 }; 0053 /** 0054 * This Enumeration is used in setUrl() to determine which items 0055 * will be removed when the given list is larger than maxItems(). 0056 * 0057 * @li RemoveTop means that items will be removed from top 0058 * @li RemoveBottom means, that items will be removed from the bottom 0059 */ 0060 enum OverLoadResolving { RemoveTop, RemoveBottom }; 0061 0062 /** 0063 * Constructs a KUrlComboBox. 0064 * @param mode is either Files, Directories or Both and controls the 0065 * following behavior: 0066 * @li Files all inserted URLs will be treated as files, therefore the 0067 * url shown in the combo will never show a trailing / 0068 * the icon will be the one associated with the file's MIME type. 0069 * @li Directories all inserted URLs will be treated as directories, will 0070 * have a trailing slash in the combobox. The current 0071 * directory will show the "open folder" icon, other 0072 * directories the "folder" icon. 0073 * @li Both Don't mess with anything, just show the url as given. 0074 * @param parent The parent object of this widget. 0075 */ 0076 explicit KUrlComboBox(Mode mode, QWidget *parent = nullptr); 0077 KUrlComboBox(Mode mode, bool rw, QWidget *parent = nullptr); 0078 /** 0079 * Destructs the combo box. 0080 */ 0081 ~KUrlComboBox() override; 0082 0083 /** 0084 * Sets the current url. This combo handles exactly one url additionally 0085 * to the default items and those set via setUrls(). So you can call 0086 * setUrl() as often as you want, it will always replace the previous one 0087 * set via setUrl(). 0088 * If @p url is already in the combo, the last item will stay there 0089 * and the existing item becomes the current item. 0090 * The current item will always have the open-directory-pixmap as icon. 0091 * 0092 * Note that you won't receive any signals, e.g. textChanged(), 0093 * returnPressed() or activated() upon calling this method. 0094 */ 0095 void setUrl(const QUrl &url); 0096 0097 /** 0098 * Inserts @p urls into the combobox below the "default urls" (see 0099 * addDefaultUrl). 0100 * 0101 * If the list of urls contains more items than maxItems, the first items 0102 * will be stripped. 0103 */ 0104 void setUrls(const QStringList &urls); 0105 0106 /** 0107 * Inserts @p urls into the combobox below the "default urls" (see 0108 * addDefaultUrl). 0109 * 0110 * If the list of urls contains more items than maxItems, the @p remove 0111 * parameter determines whether the first or last items will be stripped. 0112 */ 0113 void setUrls(const QStringList &urls, OverLoadResolving remove); 0114 0115 /** 0116 * @returns a list of all urls currently handled. The list contains at most 0117 * maxItems() items. 0118 * Use this to save the list of urls in a config-file and reinsert them 0119 * via setUrls() next time. 0120 * Note that all default urls set via addDefaultUrl() are not 0121 * returned, they will automatically be set via setUrls() or setUrl(). 0122 * You will always get fully qualified urls, i.e. with protocol like 0123 * file:/ 0124 */ 0125 QStringList urls() const; 0126 0127 /** 0128 * Sets how many items should be handled and displayed by the combobox. 0129 * @see maxItems 0130 */ 0131 void setMaxItems(int); 0132 0133 /** 0134 * @returns the maximum of items the combobox handles. 0135 * @see setMaxItems 0136 */ 0137 int maxItems() const; 0138 0139 /** 0140 * Adds a url that will always be shown in the combobox, it can't be 0141 * "rotated away". Default urls won't be returned in urls() and don't 0142 * have to be set via setUrls(). 0143 * If you want to specify a special pixmap, use the overloaded method with 0144 * the pixmap parameter. 0145 * Default URLs will be inserted into the combobox by setDefaults() 0146 */ 0147 void addDefaultUrl(const QUrl &url, const QString &text = QString()); 0148 0149 /** 0150 * Adds a url that will always be shown in the combobox, it can't be 0151 * "rotated away". Default urls won't be returned in urls() and don't 0152 * have to be set via setUrls(). 0153 * If you don't need to specify a pixmap, use the overloaded method without 0154 * the pixmap parameter. 0155 * Default URLs will be inserted into the combobox by setDefaults() 0156 */ 0157 void addDefaultUrl(const QUrl &url, const QIcon &icon, const QString &text = QString()); 0158 0159 /** 0160 * Clears all items and inserts the default urls into the combo. Will be 0161 * called implicitly upon the first call to setUrls() or setUrl() 0162 * @see addDefaultUrl 0163 */ 0164 void setDefaults(); 0165 0166 /** 0167 * Removes any occurrence of @p url. If @p checkDefaultUrls is false 0168 * default-urls won't be removed. 0169 */ 0170 void removeUrl(const QUrl &url, bool checkDefaultURLs = true); 0171 0172 /** 0173 * Reimplemented from KComboBox (from KCompletion) 0174 * @internal 0175 */ 0176 void setCompletionObject(KCompletion *compObj, bool hsig = true) override; 0177 0178 Q_SIGNALS: 0179 /** 0180 * Emitted when an item was clicked at. 0181 * @param url is the url of the now current item. 0182 */ 0183 void urlActivated(const QUrl &url); 0184 0185 protected: 0186 void mousePressEvent(QMouseEvent *event) override; 0187 void mouseMoveEvent(QMouseEvent *event) override; 0188 0189 private: 0190 friend class KUrlComboBoxPrivate; 0191 std::unique_ptr<KUrlComboBoxPrivate> const d; 0192 0193 Q_DISABLE_COPY(KUrlComboBox) 0194 }; 0195 0196 #endif // KURLCOMBOBOX_H