File indexing completed on 2024-02-25 04:00:34

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org>
0004     SPDX-FileCopyrightText: 2022 Kai Uwe Broulik <kde@broulik.de>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KFILEPLACESVIEW_H
0010 #define KFILEPLACESVIEW_H
0011 
0012 #include "kiofilewidgets_export.h"
0013 
0014 #include <QListView>
0015 #include <QUrl>
0016 
0017 #include <functional>
0018 #include <memory>
0019 
0020 class QResizeEvent;
0021 class QContextMenuEvent;
0022 
0023 class KFilePlacesViewPrivate;
0024 
0025 /**
0026  * @class KFilePlacesView kfileplacesview.h <KFilePlacesView>
0027  *
0028  * This class allows to display a KFilePlacesModel.
0029  */
0030 class KIOFILEWIDGETS_EXPORT KFilePlacesView : public QListView
0031 {
0032     Q_OBJECT
0033 public:
0034     explicit KFilePlacesView(QWidget *parent = nullptr);
0035     ~KFilePlacesView() override;
0036 
0037     /**
0038      * The teardown function signature. Custom teardown logic
0039      * may be provided via the setTeardownFunction method.
0040      * @since 5.91
0041      */
0042     using TeardownFunction = std::function<void(const QModelIndex &)>;
0043 
0044     /**
0045      * Whether hidden places, if any, are currently shown.
0046      * @since 5.91
0047      */
0048     bool allPlacesShown() const;
0049 
0050     /**
0051      * If \a enabled is true, it is allowed dropping items
0052      * above a place for e. g. copy or move operations. The application
0053      * has to take care itself to perform the operation
0054      * (see KFilePlacesView::urlsDropped()). If
0055      * \a enabled is false, it is only possible adding items
0056      * as additional place. Per default dropping on a place is
0057      * disabled.
0058      */
0059     void setDropOnPlaceEnabled(bool enabled);
0060     bool isDropOnPlaceEnabled() const;
0061 
0062     /**
0063      * If \a delay (in ms) is greater than zero, the place will
0064      * automatically be activated if an item is dragged over
0065      * and held on top of a place for at least that duraton.
0066      *
0067      * @param delay Delay in ms, default is zero.
0068      * @since 5.92
0069      */
0070     void setDragAutoActivationDelay(int delay);
0071     int dragAutoActivationDelay() const;
0072 
0073     /**
0074      * If \a enabled is true (the default), items will automatically resize
0075      * themselves to fill the view.
0076      *
0077      */
0078     void setAutoResizeItemsEnabled(bool enabled);
0079     bool isAutoResizeItemsEnabled() const;
0080 
0081     /**
0082      * Sets a custom function that will be called when teardown of
0083      * a device (e.g.\ unmounting a drive) is requested.
0084      * @since 5.91
0085      */
0086     void setTeardownFunction(TeardownFunction teardownFunc);
0087 
0088     QSize sizeHint() const override; // clazy:exclude=const-signal-or-slot
0089 
0090 public Q_SLOTS:
0091     void setUrl(const QUrl &url);
0092     void setShowAll(bool showAll);
0093 
0094     void setModel(QAbstractItemModel *model) override;
0095 
0096 protected:
0097     void keyPressEvent(QKeyEvent *event) override;
0098     void contextMenuEvent(QContextMenuEvent *event) override;
0099     void resizeEvent(QResizeEvent *event) override;
0100     void showEvent(QShowEvent *event) override;
0101     void hideEvent(QHideEvent *event) override;
0102     void dragEnterEvent(QDragEnterEvent *event) override;
0103     void dragLeaveEvent(QDragLeaveEvent *event) override;
0104     void dragMoveEvent(QDragMoveEvent *event) override;
0105     void dropEvent(QDropEvent *event) override;
0106     void paintEvent(QPaintEvent *event) override;
0107     void startDrag(Qt::DropActions supportedActions) override;
0108     void mousePressEvent(QMouseEvent *event) override;
0109 
0110 protected Q_SLOTS:
0111     void rowsInserted(const QModelIndex &parent, int start, int end) override;
0112     void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles) override;
0113 
0114 Q_SIGNALS:
0115     /**
0116      * Emitted when an item in the places view is clicked on with left mouse
0117      * button with no modifier keys pressed.
0118      *
0119      * If a storage device needs to be mounted first, this signal is emitted once
0120      * mounting has completed successfully.
0121      *
0122      * @param url The URL of the place
0123      * @since 5.91
0124      */
0125     void placeActivated(const QUrl &url);
0126 
0127     /**
0128      * Emitted when the URL \a url should be opened in a new inactive tab because
0129      * the user clicked on a place with the middle mouse button or
0130      * left-clicked with the Ctrl modifier pressed or selected "Open in New Tab"
0131      * from the context menu.
0132      *
0133      * If a storage device needs to be mounted first, this signal is emitted once
0134      * mounting has completed successfully.
0135      * @since 5.91
0136      */
0137     void tabRequested(const QUrl &url);
0138 
0139     /**
0140      * Emitted when the URL \a url should be opened in a new active tab because
0141      * the user clicked on a place with the middle mouse button with
0142      * the Shift modifier pressed or left-clicked with both the Ctrl and Shift
0143      * modifiers pressed.
0144 
0145      * If a storage device needs to be mounted first, this signal is emitted once
0146      * mounting has completed successfully.
0147      * @since 5.91
0148      */
0149     void activeTabRequested(const QUrl &url);
0150 
0151     /**
0152      * Emitted when the URL \a url should be opened in a new window because
0153      * the user left-clicked on a place with Shift modifier pressed or selected
0154      * "Open in New Window" from the context menu.
0155      *
0156      * If a storage device needs to be mounted first, this signal is emitted once
0157      * mounting has completed successfully.
0158      * @since 5.91
0159      */
0160     void newWindowRequested(const QUrl &url);
0161 
0162     /**
0163      * Emitted just before the context menu opens. This can be used to add additional
0164      * application actions to the menu.
0165      * @param index The model index of the place whose menu is about to open.
0166      * @param menu The menu that will be opened.
0167      * @since 5.91
0168      */
0169     void contextMenuAboutToShow(const QModelIndex &index, QMenu *menu);
0170 
0171     /**
0172      * Emitted when allPlacesShown changes
0173      * @since 5.91
0174      */
0175     void allPlacesShownChanged(bool allPlacesShown);
0176 
0177     void urlChanged(const QUrl &url);
0178 
0179     /**
0180      * Is emitted if items are dropped on the place \a dest.
0181      * The application has to take care itself about performing the
0182      * corresponding action like copying or moving.
0183      */
0184     void urlsDropped(const QUrl &dest, QDropEvent *event, QWidget *parent);
0185 
0186 private:
0187     friend class KFilePlacesViewPrivate;
0188     friend class KFilePlacesEventWatcher;
0189     std::unique_ptr<KFilePlacesViewPrivate> const d;
0190 };
0191 
0192 #endif