KIO

kabstractfileitemactionplugin.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2010 Sebastian Trueg <[email protected]>
4 
5  Based on konq_popupmenuplugin.h
6  SPDX-FileCopyrightText: 2008 David Faure <[email protected]>
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 QMenu;
19 class QWidget;
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 <[email protected]>
74  *
75  * @since 4.6.1
76  */
77 class KIOWIDGETS_EXPORT KAbstractFileItemActionPlugin : public QObject
78 {
79  Q_OBJECT
80 
81 public:
83 
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 
100 Q_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
KCALUTILS_EXPORT QString errorMessage(const KCalendarCore::Exception &exception)
Q_SIGNALSQ_SIGNALS
Base class for KFileItemAction plugins.
Provides information about the common properties of a group of KFileItem objects.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 03:52:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.