1/*
2 * Copyright (c) 2009 Chani Armitage <chani@kde.org>
3
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Library General Public License as
6 * published by the Free Software Foundation; either version 2, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20#ifndef PLASMA_CONTAINMENTACTIONS_H
21#define PLASMA_CONTAINMENTACTIONS_H
22
23#include <QList>
24
25#include <kplugininfo.h>
26
27#include <plasma/plasma.h>
28#include <plasma/packagestructure.h>
29#include <plasma/version.h>
30
31class QAction;
32
33namespace Plasma
34{
35
36class DataEngine;
37class Containment;
38class ContainmentActionsPrivate;
39
40/**
41 * @class ContainmentActions plasma/containmentactions.h <Plasma/ContainmentActions>
42 *
43 * @short The base ContainmentActions class
44 *
45 * "ContainmentActions" are components that provide actions (usually displaying a contextmenu) in
46 * response to an event with a position (usually a mouse event).
47 *
48 * ContainmentActions plugins are registered using .desktop files. These files should be
49 * named using the following naming scheme:
50 *
51 * plasma-containmentactions-\<pluginname\>.desktop
52 *
53 */
54
55class PLASMA_EXPORT ContainmentActions : public QObject
56{
57 Q_OBJECT
58 Q_PROPERTY(QString name READ name)
59 Q_PROPERTY(QString pluginName READ pluginName)
60 Q_PROPERTY(QString icon READ icon)
61
62 public:
63 /**
64 * Default constructor for an empty or null containmentactions
65 */
66 explicit ContainmentActions(QObject * parent = 0);
67
68 ~ContainmentActions();
69
70 /**
71 * Returns a list of all known containmentactions plugins.
72 *
73 * @return list of containmentactions plugins
74 **/
75 static KPluginInfo::List listContainmentActionsInfo();
76
77 /**
78 * Attempts to load a containmentactions
79 *
80 * Returns a pointer to the containmentactions if successful.
81 * The caller takes responsibility for the containmentactions, including
82 * deleting it when no longer needed.
83 *
84 * @param parent the parent containment. @since 4.6 null is allowed.
85 * @param name the plugin name, as returned by KPluginInfo::pluginName()
86 * @param args to send the containmentactions extra arguments
87 * @return a pointer to the loaded containmentactions, or 0 on load failure
88 **/
89 static ContainmentActions *load(Containment *parent, const QString &name, const QVariantList &args = QVariantList());
90
91 /**
92 * Attempts to load a containmentactions
93 *
94 * Returns a pointer to the containmentactions if successful.
95 * The caller takes responsibility for the containmentactions, including
96 * deleting it when no longer needed.
97 *
98 * @param parent the parent containment. @since 4.6 null is allowed.
99 * @param info KPluginInfo object for the desired containmentactions
100 * @param args to send the containmentactions extra arguments
101 * @return a pointer to the loaded containmentactions, or 0 on load failure
102 **/
103 static ContainmentActions *load(Containment *parent, const KPluginInfo &info, const QVariantList &args = QVariantList());
104
105 /**
106 * Returns the Package specialization for containmentactions.
107 */
108 static PackageStructure::Ptr packageStructure();
109
110 /**
111 * Returns the user-visible name for the containmentactions, as specified in the
112 * .desktop file.
113 *
114 * @return the user-visible name for the containmentactions.
115 **/
116 QString name() const;
117
118 /**
119 * Returns the plugin name for the containmentactions
120 */
121 QString pluginName() const;
122
123 /**
124 * Returns the icon related to this containmentactions
125 **/
126 QString icon() const;
127
128 /**
129 * @return true if initialized (usually by calling restore), false otherwise
130 */
131 bool isInitialized() const;
132
133 /**
134 * This method should be called once the plugin is loaded or settings are changed.
135 * @param config Config group to load settings
136 * @see init
137 **/
138 void restore(const KConfigGroup &config);
139
140 /**
141 * This method is called when settings need to be saved.
142 * @param config Config group to save settings
143 **/
144 virtual void save(KConfigGroup &config);
145
146 /**
147 * Returns the widget used in the configuration dialog.
148 * Add the configuration interface of the containmentactions to this widget.
149 */
150 virtual QWidget *createConfigurationInterface(QWidget *parent);
151
152 /**
153 * This method is called when the user's configuration changes are accepted
154 */
155 virtual void configurationAccepted();
156
157 /**
158 * Implement this to respond to events.
159 * The user can configure whatever button and modifier they like, so please don't look at
160 * those parameters.
161 * The event may be a QGraphicsSceneMouseEvent or a QGraphicsSceneWheelEvent.
162 */
163 virtual void contextEvent(QEvent *event);
164
165 /**
166 * Implement this to provide a list of actions that can be added to another menu
167 * for example, when right-clicking an applet, the "Activity Options" submenu is populated
168 * with this.
169 */
170 virtual QList<QAction*> contextualActions();
171
172 /**
173 * Loads the given DataEngine
174 *
175 * Tries to load the data engine given by @p name. Each engine is
176 * only loaded once, and that instance is re-used on all subsequent
177 * requests.
178 *
179 * If the data engine was not found, an invalid data engine is returned
180 * (see DataEngine::isValid()).
181 *
182 * Note that you should <em>not</em> delete the returned engine.
183 *
184 * @param name Name of the data engine to load
185 * @return pointer to the data engine if it was loaded,
186 * or an invalid data engine if the requested engine
187 * could not be loaded
188 *
189 */
190 Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
191
192 /**
193 * @return true if the containmentactions currently needs to be configured,
194 * otherwise, false
195 */
196 bool configurationRequired() const;
197
198 /**
199 * Turns a mouse or wheel event into a string suitable for a ContainmentActions
200 * @return the string representation of the event
201 */
202 static QString eventToString(QEvent *event);
203
204 /**
205 * Returns a popup position appropriate to the event and the size.
206 *
207 * @param s size of the popup
208 * @param event a pointer to the event that triggered the popup
209 * @return the preferred top-left position for the popup
210 * @since 4.6
211 */
212 QPoint popupPosition(const QSize &s, QEvent *event);
213
214 /**
215 * @reimplemented
216 */
217 bool event(QEvent *e);
218
219 /**
220 * @p newContainment the containment the plugin should be associated with.
221 * @since 4.6
222 */
223 void setContainment(Containment *newContainment);
224
225 protected:
226 /**
227 * This constructor is to be used with the plugin loading systems
228 * found in KPluginInfo and KService. The argument list is expected
229 * to have one element: the KService service ID for the desktop entry.
230 *
231 * @param parent a QObject parent; you probably want to pass in 0
232 * @param args a list of strings containing one entry: the service id
233 */
234 ContainmentActions(QObject *parent, const QVariantList &args);
235
236 /**
237 * This method is called once the containmentactions is loaded or settings are changed.
238 *
239 * @param config Config group to load settings
240 **/
241 virtual void init(const KConfigGroup &config);
242
243 /**
244 * When the containmentactions needs to be configured before being usable, this
245 * method can be called to denote that action is required
246 *
247 * @param needsConfiguring true if the applet needs to be configured,
248 * or false if it doesn't
249 */
250 void setConfigurationRequired(bool needsConfiguring = true);
251
252 /**
253 * @return the containment the plugin is associated with.
254 */
255 Containment *containment();
256
257 /**
258 * pastes the clipboard at a given location
259 */
260 void paste(QPointF scenePos, QPoint screenPos);
261
262 private:
263 friend class ContainmentActionsPackage;
264 friend class ContainmentActionsPrivate;
265 ContainmentActionsPrivate *const d;
266};
267
268} // Plasma namespace
269
270/**
271 * Register a containmentactions when it is contained in a loadable module
272 */
273#define K_EXPORT_PLASMA_CONTAINMENTACTIONS(libname, classname) \
274K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
275K_EXPORT_PLUGIN(factory("plasma_containmentactions_" #libname)) \
276K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
277
278#endif // PLASMA_CONTAINMENTACTIONS_H
279