1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2015 Olivier Goffart <ogoffart@woboq.com>
4
5 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KOVERLAYICONPLUGIN_H
9#define KOVERLAYICONPLUGIN_H
10
11#include "kiocore_export.h"
12#include <QObject>
13
14class QUrl;
15
16/*!
17 * \class KOverlayIconPlugin
18 * \inmodule KIOCore
19 *
20 * \brief Base class for overlay icon plugins.
21 *
22 * Enables file managers to show custom overlay icons on files.
23 *
24 * This plugin can be created and installed through kcoreaddons_add_plugin
25 * \code
26 * kcoreaddons_add_plugin(myoverlayplugin SOURCES myoverlayplugin.cpp INSTALL_NAMESPACE "kf6/overlayicon")
27 * target_link_libraries(myoverlayplugin KF6::KIOCore)
28 * \endcode
29 * The C++ file should look like this:
30 * \code
31 * #include <KOverlayIconPlugin>
32 *
33 * class MyOverlayPlugin : public KOverlayIconPlugin
34 * {
35 * Q_PLUGIN_METADATA(IID "org.kde.overlayicon.myplugin")
36 * Q_OBJECT
37 *
38 * public:
39 * MyOverlayPlugin() {
40 * }
41 *
42 * QStringList getOverlays(const QUrl &url) override {
43 * // Implement your logic
44 * }
45 * };
46 *
47 * #include "myoverlayplugin.moc"
48 * \endcode
49 * \since 5.16
50 */
51class KIOCORE_EXPORT KOverlayIconPlugin : public QObject
52{
53 Q_OBJECT
54public:
55 explicit KOverlayIconPlugin(QObject *parent = nullptr);
56 ~KOverlayIconPlugin() override;
57
58 /*!
59 * Returns a list of overlay icons to add to a file
60 * This can be a path to an icon, or the icon name
61 *
62 * This function is called from the main thread and must not block.
63 * It is recommended to have a cache. And if the item is not in cache
64 * just return an empty list and call the overlaysChanged when the
65 * information is available.
66 */
67 virtual QStringList getOverlays(const QUrl &item) = 0;
68Q_SIGNALS:
69 /*!
70 * Emit this signal when the list of overlay icons changed for a given URL
71 */
72 void overlaysChanged(const QUrl &url, const QStringList &overlays);
73};
74
75#endif
76

source code of kio/src/core/koverlayiconplugin.h