File indexing completed on 2023-12-03 07:45:28

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      * @since 4.1
0078      */
0079     void setAutoResizeItemsEnabled(bool enabled);
0080     bool isAutoResizeItemsEnabled() const;
0081 
0082     /**
0083      * Sets a custom function that will be called when teardown of
0084      * a device (e.g.\ unmounting a drive) is requested.
0085      * @since 5.91
0086      */
0087     void setTeardownFunction(TeardownFunction teardownFunc);
0088 
0089 public Q_SLOTS:
0090     void setUrl(const QUrl &url);
0091     void setShowAll(bool showAll);
0092 
0093     // TODO KF6: make it a public method, not a slot
0094     QSize sizeHint() const override; // clazy:exclude=const-signal-or-slot
0095 
0096     void setModel(QAbstractItemModel *model) override;
0097 
0098 protected:
0099     void keyPressEvent(QKeyEvent *event) override;
0100     void contextMenuEvent(QContextMenuEvent *event) override;
0101     void resizeEvent(QResizeEvent *event) override;
0102     void showEvent(QShowEvent *event) override;
0103     void hideEvent(QHideEvent *event) override;
0104     void dragEnterEvent(QDragEnterEvent *event) override;
0105     void dragLeaveEvent(QDragLeaveEvent *event) override;
0106     void dragMoveEvent(QDragMoveEvent *event) override;
0107     void dropEvent(QDropEvent *event) override;
0108     void paintEvent(QPaintEvent *event) override;
0109     void startDrag(Qt::DropActions supportedActions) override;
0110     void mousePressEvent(QMouseEvent *event) override;
0111 
0112 protected Q_SLOTS:
0113     void rowsInserted(const QModelIndex &parent, int start, int end) override;
0114     void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QVector<int> &roles) override;
0115 
0116 Q_SIGNALS:
0117     /**
0118      * Emitted when an item in the places view is clicked on with left mouse
0119      * button with no modifier keys pressed.
0120      *
0121      * If a storage device needs to be mounted first, this signal is emitted once
0122      * mounting has completed successfully.
0123      *
0124      * @param url The URL of the place
0125      * @since 5.91
0126      */
0127     void placeActivated(const QUrl &url);
0128 
0129     /**
0130      * Emitted when the URL \a url should be opened in a new inactive tab because
0131      * the user clicked on a place with the middle mouse button or
0132      * left-clicked with the Ctrl modifier pressed or selected "Open in New Tab"
0133      * from the context menu.
0134      *
0135      * If a storage device needs to be mounted first, this signal is emitted once
0136      * mounting has completed successfully.
0137      * @since 5.91
0138      */
0139     void tabRequested(const QUrl &url);
0140 
0141     /**
0142      * Emitted when the URL \a url should be opened in a new active tab because
0143      * the user clicked on a place with the middle mouse button with
0144      * the Shift modifier pressed or left-clicked with both the Ctrl and Shift
0145      * modifiers pressed.
0146 
0147      * If a storage device needs to be mounted first, this signal is emitted once
0148      * mounting has completed successfully.
0149      * @since 5.91
0150      */
0151     void activeTabRequested(const QUrl &url);
0152 
0153     /**
0154      * Emitted when the URL \a url should be opened in a new window because
0155      * the user left-clicked on a place with Shift modifier pressed or selected
0156      * "Open in New Window" from the context menu.
0157      *
0158      * If a storage device needs to be mounted first, this signal is emitted once
0159      * mounting has completed successfully.
0160      * @since 5.91
0161      */
0162     void newWindowRequested(const QUrl &url);
0163 
0164     /**
0165      * Emitted just before the context menu opens. This can be used to add additional
0166      * application actions to the menu.
0167      * @param index The model index of the place whose menu is about to open.
0168      * @param menu The menu that will be opened.
0169      * @since 5.91
0170      */
0171     void contextMenuAboutToShow(const QModelIndex &index, QMenu *menu);
0172 
0173     /**
0174      * Emitted when allPlacesShown changes
0175      * @since 5.91
0176      */
0177     void allPlacesShownChanged(bool allPlacesShown);
0178 
0179     void urlChanged(const QUrl &url);
0180 
0181     /**
0182      * Is emitted if items are dropped on the place \a dest.
0183      * The application has to take care itself about performing the
0184      * corresponding action like copying or moving.
0185      */
0186     void urlsDropped(const QUrl &dest, QDropEvent *event, QWidget *parent);
0187 
0188 private:
0189     friend class KFilePlacesViewPrivate;
0190     friend class KFilePlacesEventWatcher;
0191     std::unique_ptr<KFilePlacesViewPrivate> const d;
0192 };
0193 
0194 #endif