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