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 | |
31 | class QAction; |
32 | |
33 | namespace Plasma |
34 | { |
35 | |
36 | class DataEngine; |
37 | class Containment; |
38 | class 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 | |
55 | class 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 (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) \ |
274 | K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \ |
275 | K_EXPORT_PLUGIN(factory("plasma_containmentactions_" #libname)) \ |
276 | K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) |
277 | |
278 | #endif // PLASMA_CONTAINMENTACTIONS_H |
279 | |