1 | /* This file is part of the KDE project |
2 | Copyright (C) 2010 Sebastian Trueg <trueg@kde.org> |
3 | Based on konq_popupmenuplugin.h Copyright 2008 David Faure <faure@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or modify |
6 | it under the terms of the GNU Library General Public License as published |
7 | by the Free Software Foundation; either version 2 of the License or |
8 | ( at your option ) version 3 or, at the discretion of KDE e.V. |
9 | ( which shall act as a proxy as in section 14 of the GPLv3 ), any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef KABSTRACTFILEITEMACTION_PLUGIN_H |
23 | #define KABSTRACTFILEITEMACTION_PLUGIN_H |
24 | |
25 | #include <kio/kio_export.h> |
26 | #include <QtCore/QObject> |
27 | |
28 | class QAction; |
29 | class ; |
30 | class QWidget; |
31 | class KFileItemListProperties; |
32 | |
33 | /** |
34 | * @brief Base class for KFileItemAction plugins. |
35 | * |
36 | * Please try to use servicemenus first, if you simply need to add |
37 | * actions to the popup menu for one or more mimetypes. |
38 | * |
39 | * However if you need some dynamic logic, like "only show this item if |
40 | * two files are selected", or "show a submenu with a variable number of actions", |
41 | * then you have to implement a KAbstractFileItemActionPlugin subclass. |
42 | * |
43 | * As always plugins need to be exported via the K_EXPORT_PLUGIN macro like so: |
44 | * |
45 | * \code |
46 | * K_PLUGIN_FACTORY(MyActionPluginFactory, registerPlugin<MyActionPlugin>();) |
47 | * K_EXPORT_PLUGIN(MyActionPluginFactory("myactionplugin")) |
48 | * \endcode |
49 | * |
50 | * A desktop file is necessary to register the plugin with the KDE plugin system: |
51 | * |
52 | * \code |
53 | * [Desktop Entry] |
54 | * Encoding=UTF-8 |
55 | * Type=Service |
56 | * Name=My fancy action plugin |
57 | * X-KDE-Library=myactionplugin |
58 | * ServiceTypes=KFileItemAction/Plugin |
59 | * MimeType=some/mimetype; |
60 | * \endcode |
61 | * |
62 | * Note the \p KFileItemAction/Plugin service type which is used by |
63 | * KFileItemActions::addServicePluginActionsTo() to load all available plugins |
64 | * and the \p MimeType field which specifies for which types of file items |
65 | * the setup() method should be called. |
66 | * |
67 | * As with all KDE plugins one needs to install the plugin as a module. In |
68 | * cmake terms this looks roughly as follows: |
69 | * |
70 | * \code |
71 | * kde4_add_plugin(myactionplugin myactionplugin.cpp) |
72 | * target_link_libraries(myactionplugin ${KDE4_KIO_LIBS}) |
73 | * install(TARGETS myactionplugin DESTINATION ${PLUGIN_INSTALL_DIR}) |
74 | * install(FILES myactionplugin.desktop DESTINATION ${SERVICES_INSTALL_DIR}) |
75 | * \endcode |
76 | * |
77 | * @author Sebastian Trueg <trueg@kde.org> |
78 | * |
79 | * @since 4.6.1 |
80 | */ |
81 | class KIO_EXPORT KAbstractFileItemActionPlugin : public QObject |
82 | { |
83 | Q_OBJECT |
84 | |
85 | public: |
86 | KAbstractFileItemActionPlugin(QObject *parent); |
87 | |
88 | virtual ~KAbstractFileItemActionPlugin(); |
89 | |
90 | /** |
91 | * Implement the actions method in the plugin in order to create actions. |
92 | * |
93 | * @param fileItemInfos The information about the selected file items. |
94 | * (Which file items, their common mimetype, etc.) |
95 | * @param parentWidget A parent widget for error messages or the like. |
96 | * @return List of actions, that should added to e. g. the popup menu. |
97 | * It is recommended to use the KAbstractFileItemActionPlugin as parent |
98 | * of the actions. |
99 | */ |
100 | virtual QList<QAction*> actions(const KFileItemListProperties &fileItemInfos, |
101 | QWidget *parentWidget) = 0; |
102 | }; |
103 | |
104 | #endif |
105 | |