Marble

RenderPlugin.h
1// SPDX-License-Identifier: LGPL-2.1-or-later
2//
3// SPDX-FileCopyrightText: 2008 Torsten Rahn <tackat@kde.org>
4// SPDX-FileCopyrightText: 2008 Inge Wallin <inge@lysator.liu.se>
5// SPDX-FileCopyrightText: 2011, 2012 Bernhard Beschow <bbeschow@cs.tu-berlin.de>
6// SPDX-FileCopyrightText: 2012 Illya Kovalevskyy <illya.kovalevskyy@gmail.com>
7//
8
9#ifndef MARBLE_RENDERPLUGIN_H
10#define MARBLE_RENDERPLUGIN_H
11
12#include <QObject>
13#include <QString>
14#include <QRegion>
15
16#include "RenderPluginInterface.h"
17#include "marble_export.h"
18
19
20class QAction;
21class QActionGroup;
22class QStandardItem;
23
24namespace Marble
25{
26
27class MarbleModel;
28class RenderPluginModel;
29
30/**
31 * @brief The abstract class that creates a renderable item
32 *
33 * Renderable Plugins can be used to extend Marble's functionality:
34 * They allow to draw stuff on top of the map / globe
35 *
36 */
37
38class MARBLE_EXPORT RenderPlugin : public QObject, public RenderPluginInterface
39{
40 Q_OBJECT
41
42 Q_PROPERTY ( QString name READ name CONSTANT )
43 Q_PROPERTY ( QString nameId READ nameId CONSTANT )
44 Q_PROPERTY ( QString version READ version CONSTANT )
45 Q_PROPERTY ( QString description READ description CONSTANT )
46 Q_PROPERTY ( bool enabled READ enabled WRITE setEnabled NOTIFY enabledChanged )
47 Q_PROPERTY ( bool visible READ visible WRITE setVisible NOTIFY visibilityChanged )
48 Q_PROPERTY ( bool userCheckable READ isUserCheckable WRITE setUserCheckable NOTIFY userCheckableChanged )
49
50 public:
51 /**
52 * @brief A Type of plugin
53 */
55 UnknownRenderType,
56 TopLevelRenderType,
57 PanelRenderType,
58 OnlineRenderType,
59 ThemeRenderType
60 };
61
62 explicit RenderPlugin( const MarbleModel *marbleModel );
63 ~RenderPlugin() override;
64
65 /**
66 * @brief String that should be displayed in GUI
67 *
68 * Using a "&" you can suggest key shortcuts
69 *
70 * Example: "&Stars"
71 *
72 * @return string for gui usage
73 */
74 virtual QString guiString() const = 0;
75
76 /**
77 * @brief Creation a new instance of the plugin
78 *
79 * This method is used to create a new object of the current
80 * plugin using the @p marbleModel given.
81 *
82 * @param marbleModel base model
83 * @return new instance of current plugin
84 * @note Typically this method is implemented with the help of the MARBLE_PLUGIN() macro.
85 */
86 virtual RenderPlugin *newInstance( const MarbleModel *marbleModel ) const = 0;
87
88 /**
89 * @brief Access to the MarbleModel
90 *
91 * Internal way to access the model of marble.
92 * Can be used to interact with the main application
93 *
94 * @return marble model
95 * @see MarbleModel
96 */
97 const MarbleModel* marbleModel() const;
98
99 /**
100 * @brief Getting all actions
101 *
102 * This method is used by the main window to get all of the actions that this
103 * plugin defines. There is no guarantee where the main window will place the
104 * actions but it will generally be in a Menu. The returned QList should
105 * also contain all of the actions returned by @see toolbarActions().
106 *
107 * @return a list of grouped actions
108 */
109 virtual const QList<QActionGroup*>* actionGroups() const;
110
111 /**
112 * @brief Getting all actions which should be placed in the toolbar
113 *
114 * This method returns a subset of the actions returned by @see actions() which
115 * are intended to be placed in a more prominent place such as a toolbar above
116 * the Marble Widget. You are not guaranteed that they will be in an actual
117 * toolbar but they will be visible and discoverable
118 *
119 * @return a list of grouped toolbar actions
120 */
121 virtual const QList<QActionGroup*>* toolbarActionGroups() const;
122
123 /**
124 * @brief is enabled
125 *
126 * This method indicates enableability of the plugin
127 *
128 * If plugin is enabled it going to be displayed in Marble Menu
129 * as active action which can be @see setUserCheckable
130 *
131 * @return enableability of the plugin
132 * @see setEnabled
133 */
134 bool enabled() const;
135
136 /**
137 * @brief is visible
138 *
139 * This method indicates visibility of the plugin
140 *
141 * If plugin is visible you can see it on the map/globe
142 *
143 * @return visibility of the plugin
144 * @see setVisible
145 */
146 bool visible() const;
147
148 /**
149 * @brief is user checkable
150 *
151 * This method indicates user checkability of plugin's
152 * action displayed in application menu
153 *
154 * Can control plugin visibility
155 *
156 * @warning User can do it only if @see enabled is true
157 *
158 * @return checkability of the plugin
159 * @see setUserCheckable
160 */
161 bool isUserCheckable() const;
162
163 /**
164 * @brief Settings of the plugin
165 *
166 * Settings is the map (hash table) of plugin's settings
167 * This method is called to determine the current settings of the plugin
168 * for serialization, e.g. when closing the application.
169 *
170 * @return plugin's settings
171 * @see setSettings
172 */
173 virtual QHash<QString,QVariant> settings() const;
174
175 /**
176 * @brief Set the settings of the plugin
177 *
178 * Usually this is called at startup to restore saved settings.
179 *
180 * @param new plugin's settings
181 * @see settings
182 */
183 virtual void setSettings( const QHash<QString,QVariant> &settings );
184
185 /**
186 * @brief Render type of the plugin
187 *
188 * Function for returning the type of plugin this is for.
189 * This affects where in the menu tree the action() is placed.
190 *
191 * @see RenderType
192 * @return: The type of render plugin this is
193 */
194 virtual RenderType renderType() const;
195
196 RenderState renderState() const override;
197
198 QString runtimeTrace() const override;
199
200 public Q_SLOTS:
201 /**
202 * @brief setting enabled
203 *
204 * If @p enabled = true, plugin will be enabled
205 *
206 * If plugin is enabled it will be possible to show/hide it
207 * from menu (access from UI)
208 *
209 * @param enabled plugin's enabled state
210 * @see enabled
211 */
212 void setEnabled( bool enabled );
213
214 /**
215 * @brief setting visible
216 *
217 * If @p visible = true, plugin will be visible
218 *
219 * @param visible visibility of the plugin
220 * @see visible
221 */
222 void setVisible( bool visible );
223
224 /**
225 * @brief setting user checkable
226 *
227 * If @p isUserCheckable = true, user will get an
228 * option to control visibility in application menu
229 *
230 * @param isUserCheckable user checkability of the plugin
231 * @see isUserCheckable
232 */
233 void setUserCheckable(bool isUserCheckable);
234
235 /**
236 * @brief Passes an empty set of settings to the plugin
237 *
238 * Well behaving plugins restore their settings to default values as a result of calling this method.
239 *
240 */
241 void restoreDefaultSettings();
242
243 /**
244 * @brief Full list of the settings keys
245 *
246 * This method should be used to get all possible
247 * settings' keys for the plugin's settings
248 *
249 * @return list with the keys of settings
250 */
251 QStringList settingKeys() const;
252
253 /**
254 * @brief Change setting key's values
255 * @param key setting key
256 * @param value new value
257 *
258 * This method applies @p value for the @p key
259 *
260 * @return successfully changed or not
261 */
262 bool setSetting( const QString & key, const QVariant & value );
263
264 /**
265 * @brief Getting setting value from the settings
266 * @param key setting's key index
267 *
268 * This method should be used to get current value of @p key
269 * in settings hash table
270 *
271 * @return setting value
272 */
273 QVariant setting( const QString & key ) const;
274
275 /**
276 * @brief Plugin's menu action
277 *
278 * The action is checkable and controls the visibility of the plugin.
279 *
280 * @return action, displayed in menu
281 */
282 QAction *action() const;
283
284 Q_SIGNALS:
285 /**
286 * This signal is emitted if the visibility is changed with @see setVisible
287 */
288 void visibilityChanged( bool visible, const QString &nameId );
289
290 /**
291 * This signal is emitted if the enabled property is changed with @see setEnabled
292 */
293 void enabledChanged( bool enable );
294
295 /**
296 * This signal is emitted if the user checkable property is changed with @see setUserCheckable
297 */
298 void userCheckableChanged(bool isUserCheckable);
299
300 /**
301 * This signal is emitted if the settings of the RenderPlugin changed.
302 */
303 void settingsChanged( const QString& nameId );
304
305 /**
306 * This signal is emitted if the actions that the plugin supports change in
307 * any way
308 */
310
311 /**
312 * This signal is emitted if an update of the view is needed. If available with the
313 * @p dirtyRegion which is the region the view will change in. If dirtyRegion.isEmpty() returns
314 * true, the whole viewport has to be repainted.
315 */
316 void repaintNeeded( const QRegion& dirtyRegion = QRegion() );
317
318 protected:
319 bool eventFilter( QObject *, QEvent * ) override;
320
321 private:
322 friend class RenderPluginModel;
323
324 QStandardItem *item();
325
326 void applyItemState();
327 void retrieveItemState();
328
329 private:
330 Q_DISABLE_COPY( RenderPlugin )
331 class Private;
332 Private * const d;
333};
334
335#define MARBLE_PLUGIN(T) public:\
336 RenderPlugin* newInstance( const MarbleModel *marbleModel ) const override { return new T( marbleModel ); }
337}
338
339#endif
The data model (not based on QAbstractModel) for a MarbleWidget.
Definition MarbleModel.h:87
The class that specifies the Marble layer interface of a plugin.
Provides common access to various kinds of plugins without having to know about their details.
The abstract class that creates a renderable item.
virtual QString guiString() const =0
String that should be displayed in GUI.
virtual RenderPlugin * newInstance(const MarbleModel *marbleModel) const =0
Creation a new instance of the plugin.
void enabledChanged(bool enable)
This signal is emitted if the enabled property is changed with.
void actionGroupsChanged()
This signal is emitted if the actions that the plugin supports change in any way.
RenderType
A Type of plugin.
void repaintNeeded(const QRegion &dirtyRegion=QRegion())
This signal is emitted if an update of the view is needed.
void userCheckableChanged(bool isUserCheckable)
This signal is emitted if the user checkable property is changed with.
void settingsChanged(const QString &nameId)
This signal is emitted if the settings of the RenderPlugin changed.
void visibilityChanged(bool visible, const QString &nameId)
This signal is emitted if the visibility is changed with.
Binds a QML item to a specific geodetic location in screen coordinates.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:50:53 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.