Marble

RenderPlugin.h
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 //
3 // SPDX-FileCopyrightText: 2008 Torsten Rahn <[email protected]>
4 // SPDX-FileCopyrightText: 2008 Inge Wallin <[email protected]>
5 // SPDX-FileCopyrightText: 2011, 2012 Bernhard Beschow <[email protected]>
6 // SPDX-FileCopyrightText: 2012 Illya Kovalevskyy <[email protected]>
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 
20 class QAction;
21 class QActionGroup;
22 class QStandardItem;
23 
24 namespace Marble
25 {
26 
27 class MarbleModel;
28 class 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 
38 class 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  */
54  enum RenderType {
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  */
309  void actionGroupsChanged();
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 abstract class that creates a renderable item.
Definition: RenderPlugin.h:38
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.
Binds a QML item to a specific geodetic location in screen coordinates.
RenderType
A Type of plugin.
Definition: RenderPlugin.h:54
unsigned int version()
The data model (not based on QAbstractModel) for a MarbleWidget.
Definition: MarbleModel.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 03:53:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.