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 kabstractfileitemactionplugin.h <KAbstractFileItemActionPlugin>
24 *
25 * @brief Base class for KFileItemAction plugins.
26 *
27 * KFileItemAction plugins allow dynamic features to be added to the context
28 * menus for files and directories when browsing.
29 *
30 * Most filetype-based popup menu items can be implemented using servicemenus
31 * linked to MIME types, and that should be the preferred way of doing this.
32 * However, complex scenarios such as showing submenus with a variable number of
33 * actions or only showing an item if exactly two files are selected need to be
34 * implemented as a KFileItemAction plugin.
35 *
36 * To create such a plugin, subclass KAbstractFileItemActionPlugin and implement
37 * actions() to return the actions to want to add to the context menu. Then
38 * create a plugin in the usual KPluginFactory based way:
39 * \code
40 * K_PLUGIN_CLASS_WITH_JSON(MyActionPlugin, "myactionplugin.json")
41 * #include <thisfile.moc>
42 * \endcode
43 *
44 * A desktop file is necessary to register the plugin with the KDE plugin system:
45 *
46 * \code
47 * [Desktop Entry]
48 * Type=Service
49 * Name=My fancy action plugin
50 * X-KDE-Library=myactionplugin
51 * X-KDE-ServiceTypes=KFileItemAction/Plugin
52 * MimeType=some/mimetype;
53 * \endcode
54 *
55 * Note the \p KFileItemAction/Plugin service type which is used by
56 * KFileItemActions::addServicePluginActionsTo() to load all available plugins
57 * and the \p MimeType field which specifies for which types of file items
58 * the setup() method should be called.
59 *
60 * The desktop file contents must also be compiled into the plugin as JSON data.
61 * The following CMake code builds and installs the plugin:
62 * \code
63 * kcoreaddons_add_plugin(myactionplugin SOURCES myactionplugin.cpp INSTALL_NAMESPACE "kf5/kfileitemaction")
64 * kcoreaddons_desktop_to_json(myactionplugin myactionplugin.desktop) # generate the json file
65 *
66 * target_link_libraries(myactionplugin KF5::KIOWidgets)
67 * \endcode
68 *
69 * @note the plugin should be installed in the "kf5/kfileitemaction" subfolder of $QT_PLUGIN_PATH.
70 * @note If the plugin has a lower priority and should show up in the "Actions" submenu,
71 * you can set the X-KDE-Show-In-Submenu property to true.
72 *
73 * @author Sebastian Trueg <trueg@kde.org>
74 *
75 * @since 4.6.1
76 */
77class KIOWIDGETS_EXPORT KAbstractFileItemActionPlugin : public QObject
78{
79 Q_OBJECT
80
81public:
82 explicit KAbstractFileItemActionPlugin(QObject *parent);
83
84 ~KAbstractFileItemActionPlugin() override;
85
86 /**
87 * Implement the actions method in the plugin in order to create actions.
88 *
89 * The returned actions should have the KAbstractFileItemActionPlugin object
90 * as their parent.
91 *
92 * @param fileItemInfos Information about the selected file items.
93 * @param parentWidget To be used as parent for the returned QActions
94 *
95 * @return A list of actions to be added to a contextual menu for the file
96 * items.
97 */
98 virtual QList<QAction *> actions(const KFileItemListProperties &fileItemInfos, QWidget *parentWidget) = 0;
99
100Q_SIGNALS:
101 /**
102 * Emits an error which will be displayed to the user
103 * @since 5.82
104 */
105 void error(const QString &errorMessage);
106};
107
108#endif
109

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