1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2010 Sebastian Trueg <trueg@kde.org>
4
5 Based on konq_popupmenuplugin.h
6 SPDX-FileCopyrightText: 2008 David Faure <faure@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
9*/
10
11#ifndef KABSTRACTFILEITEMACTION_PLUGIN_H
12#define KABSTRACTFILEITEMACTION_PLUGIN_H
13
14#include "kiowidgets_export.h"
15#include <QObject>
16
17class QAction;
18class QMenu;
19class QWidget;
20class KFileItemListProperties;
21
22/*!
23 * \class KAbstractFileItemActionPlugin
24 * \inmodule KIOWidgets
25 *
26 * \brief Base class for KFileItemAction plugins.
27 *
28 * KFileItemAction plugins allow dynamic features to be added to the context
29 * menus for files and directories when browsing.
30 *
31 * Most filetype-based popup menu items can be implemented using servicemenus
32 * linked to MIME types, and that should be the preferred way of doing this.
33 * However, complex scenarios such as showing submenus with a variable number of
34 * actions or only showing an item if exactly two files are selected need to be
35 * implemented as a KFileItemAction plugin.
36 *
37 * To create such a plugin, subclass KAbstractFileItemActionPlugin and implement
38 * actions() to return the actions to want to add to the context menu. Then
39 * create a plugin in the usual KPluginFactory based way:
40 * \code
41 * K_PLUGIN_CLASS_WITH_JSON(MyActionPlugin, "myactionplugin.json")
42 * #include <thisfile.moc>
43 * \endcode
44 *
45 * A desktop file is necessary to register the plugin with the KDE plugin system:
46 *
47 * \code
48 * [Desktop Entry]
49 * Type=Service
50 * Name=My fancy action plugin
51 * X-KDE-Library=myactionplugin
52 * X-KDE-ServiceTypes=KFileItemAction/Plugin
53 * MimeType=some/mimetype;
54 * \endcode
55 *
56 * Note the KFileItemAction/Plugin service type which is used by
57 * KFileItemActions::addServicePluginActionsTo() to load all available plugins
58 * and the MimeType field which specifies for which types of file items
59 * the setup() method should be called.
60 *
61 * The desktop file contents must also be compiled into the plugin as JSON data.
62 * The following CMake code builds and installs the plugin:
63 * \code
64 * kcoreaddons_add_plugin(myactionplugin SOURCES myactionplugin.cpp INSTALL_NAMESPACE "kf6/kfileitemaction")
65 * kcoreaddons_desktop_to_json(myactionplugin myactionplugin.desktop) # generate the json file if necessary
66 *
67 * target_link_libraries(myactionplugin KF5::KIOWidgets)
68 * \endcode
69 *
70 * \note The plugin should be installed in the "kf5/kfileitemaction" subfolder of $QT_PLUGIN_PATH.
71 *
72 * \note If the plugin has a lower priority and should show up in the "Actions" submenu,
73 * you can set the X-KDE-Show-In-Submenu property to true.
74 *
75 * \since 4.6.1
76 */
77class KIOWIDGETS_EXPORT KAbstractFileItemActionPlugin : public QObject
78{
79 Q_OBJECT
80
81public:
82 /*!
83 *
84 */
85 explicit KAbstractFileItemActionPlugin(QObject *parent);
86
87 ~KAbstractFileItemActionPlugin() override;
88
89 // TODO KF7 make this asynchronous and stoppable, so a bad plugin cannot impact too much the application process
90 // KIO could enforce a timeout and run it in a Thread
91 /*!
92 * Implement the actions method in the plugin in order to create actions.
93 *
94 * \a fileItemInfos Information about the selected file items.
95 *
96 * \a parentWidget To be used as parent for the returned QActions
97 *
98 * Returns a list of actions to be added to a contextual menu for the file items.
99 */
100 virtual QList<QAction *> actions(const KFileItemListProperties &fileItemInfos, QWidget *parentWidget) = 0;
101
102Q_SIGNALS:
103 /*!
104 * Emits an error which will be displayed to the user
105 * \since 5.82
106 */
107 void error(const QString &errorMessage);
108};
109
110#endif
111

source code of kio/src/widgets/kabstractfileitemactionplugin.h