File indexing completed on 2024-06-16 10:06:12

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2010 Sebastian Trueg <trueg@kde.org>
0004 
0005     Based on konq_popupmenuplugin.h
0006     SPDX-FileCopyrightText: 2008 David Faure <faure@kde.org>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0009 */
0010 
0011 #ifndef KABSTRACTFILEITEMACTION_PLUGIN_H
0012 #define KABSTRACTFILEITEMACTION_PLUGIN_H
0013 
0014 #include "kiowidgets_export.h"
0015 #include <QObject>
0016 
0017 class QAction;
0018 class QMenu;
0019 class QWidget;
0020 class KFileItemListProperties;
0021 
0022 /**
0023  * @class KAbstractFileItemActionPlugin kabstractfileitemactionplugin.h <KAbstractFileItemActionPlugin>
0024  *
0025  * @brief Base class for KFileItemAction plugins.
0026  *
0027  * KFileItemAction plugins allow dynamic features to be added to the context
0028  * menus for files and directories when browsing.
0029  *
0030  * Most filetype-based popup menu items can be implemented using servicemenus
0031  * linked to MIME types, and that should be the preferred way of doing this.
0032  * However, complex scenarios such as showing submenus with a variable number of
0033  * actions or only showing an item if exactly two files are selected need to be
0034  * implemented as a KFileItemAction plugin.
0035  *
0036  * To create such a plugin, subclass KAbstractFileItemActionPlugin and implement
0037  * actions() to return the actions to want to add to the context menu.  Then
0038  * create a plugin in the usual KPluginFactory based way:
0039  * \code
0040  * K_PLUGIN_CLASS_WITH_JSON(MyActionPlugin, "myactionplugin.json")
0041  * #include <thisfile.moc>
0042  * \endcode
0043  *
0044  * A desktop file is necessary to register the plugin with the KDE plugin system:
0045  *
0046  * \code
0047  * [Desktop Entry]
0048  * Type=Service
0049  * Name=My fancy action plugin
0050  * X-KDE-Library=myactionplugin
0051  * X-KDE-ServiceTypes=KFileItemAction/Plugin
0052  * MimeType=some/mimetype;
0053  * \endcode
0054  *
0055  * Note the \p KFileItemAction/Plugin service type which is used by
0056  * KFileItemActions::addServicePluginActionsTo() to load all available plugins
0057  * and the \p MimeType field which specifies for which types of file items
0058  * the setup() method should be called.
0059  *
0060  * The desktop file contents must also be compiled into the plugin as JSON data.
0061  * The following CMake code builds and installs the plugin:
0062  * \code
0063  * kcoreaddons_add_plugin(myactionplugin SOURCES myactionplugin.cpp INSTALL_NAMESPACE "kf5/kfileitemaction")
0064  * kcoreaddons_desktop_to_json(myactionplugin myactionplugin.desktop) # generate the json file
0065  *
0066  * target_link_libraries(myactionplugin KF5::KIOWidgets)
0067  * \endcode
0068  *
0069  * @note the plugin should be installed in the "kf5/kfileitemaction" subfolder of $QT_PLUGIN_PATH.
0070  * @note If the plugin has a lower priority and should show up in the "Actions" submenu,
0071  * you can set the X-KDE-Show-In-Submenu property to true.
0072  *
0073  * @author Sebastian Trueg <trueg@kde.org>
0074  *
0075  * @since 4.6.1
0076  */
0077 class KIOWIDGETS_EXPORT KAbstractFileItemActionPlugin : public QObject
0078 {
0079     Q_OBJECT
0080 
0081 public:
0082     KAbstractFileItemActionPlugin(QObject *parent);
0083 
0084     ~KAbstractFileItemActionPlugin() override;
0085 
0086     /**
0087      * Implement the actions method in the plugin in order to create actions.
0088      *
0089      * The returned actions should have the KAbstractFileItemActionPlugin object
0090      * as their parent.
0091      *
0092      * @param fileItemInfos  Information about the selected file items.
0093      * @param parentWidget   To be used as parent for the returned QActions
0094      *
0095      * @return A list of actions to be added to a contextual menu for the file
0096      *         items.
0097      */
0098     virtual QList<QAction *> actions(const KFileItemListProperties &fileItemInfos, QWidget *parentWidget) = 0;
0099 
0100 Q_SIGNALS:
0101     /**
0102      * Emits an error which will be displayed to the user
0103      * @since 5.82
0104      */
0105     void error(const QString &errorMessage);
0106 };
0107 
0108 #endif