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 | |
17 | class QAction; |
18 | class ; |
19 | class QWidget; |
20 | class 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 | */ |
77 | class KIOWIDGETS_EXPORT KAbstractFileItemActionPlugin : public QObject |
78 | { |
79 | Q_OBJECT |
80 | |
81 | public: |
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 | |
102 | Q_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 | |