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
28class QAction;
29class QMenu;
30class QWidget;
31class 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 */
81class KIO_EXPORT KAbstractFileItemActionPlugin : public QObject
82{
83 Q_OBJECT
84
85public:
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