1 /***************************************************************************
2     qgslayoutdesignerinterface.h
3      ---------------------
4     Date                 : July 2017
5     Copyright            : (C) 2017 Nyall Dawson
6     Email                : nyall dot dawson at gmail dot com
7  ***************************************************************************
8  *                                                                         *
9  *   This program is free software; you can redistribute it and/or modify  *
10  *   it under the terms of the GNU General Public License as published by  *
11  *   the Free Software Foundation; either version 2 of the License, or     *
12  *   (at your option) any later version.                                   *
13  *                                                                         *
14  ***************************************************************************/
15 
16 #ifndef QGSLAYOUTDESIGNERINTERFACE_H
17 #define QGSLAYOUTDESIGNERINTERFACE_H
18 
19 #include "qgis_gui.h"
20 #include "qgis_sip.h"
21 #include <QObject>
22 
23 class QgsLayout;
24 class QgsLayoutView;
25 class QgsLayoutItem;
26 class QgsMessageBar;
27 class QgsFeature;
28 class QgsMasterLayoutInterface;
29 class QMenu;
30 class QDockWidget;
31 class QToolBar;
32 
33 /**
34  * \ingroup gui
35  * \class QgsLayoutDesignerInterface
36  * \brief A common interface for layout designer dialogs and widgets.
37  *
38  * Provides a common interface and stable API for layout designer dialogs and widgets.
39  * This interface can be used by plugins and scripts to interact with
40  * open layout designer dialogs.
41  *
42  * \note Layout designer dialogs are transitory. They are created only on demand
43  * (when a user opens the dialog) and are deleted as soon as the user closes the dialog.
44  * There can be multiple designer dialogs open at any one time, and each is a separate
45  * instance of the dialog and QgsLayoutDesignerInterface. Accordingly, plugins must
46  * take care to react to newly created designer dialogs and apply their customizations
47  * to all newly created dialogs. This can be done by listening for the QgisInterface::layoutDesignerOpened
48  * signal. Plugins must also listen for the QgisInterface::layoutDesignerWillBeClosed
49  * signal and gracefully cleanup any customizations before the designer dialog is
50  * deleted.
51  *
52  * \since QGIS 3.0
53  */
54 class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
55 {
56 
57 #ifdef SIP_RUN
58     SIP_CONVERT_TO_SUBCLASS_CODE
59     if ( qobject_cast<QgsLayoutDesignerInterface *>( sipCpp ) )
60       sipType = sipType_QgsLayoutDesignerInterface;
61     else
62       sipType = NULL;
63     SIP_END
64 #endif
65 
66     Q_OBJECT
67 
68   public:
69 
70     //! Standard designer tools which are always available for use
71     enum StandardTool
72     {
73       ToolMoveItemContent, //!< Move item content tool
74       ToolMoveItemNodes, //!< Move item nodes tool
75     };
76 
77     /**
78      * Constructor for QgsLayoutDesignerInterface.
79      */
80     QgsLayoutDesignerInterface( QObject *parent SIP_TRANSFERTHIS = nullptr )
QObject(parent)81       : QObject( parent )
82     {}
83 
84     /**
85      * Returns the current layout displayed in the designer.
86      * \see view()
87      */
88     virtual QgsLayout *layout() = 0;
89 
90     /**
91      * Returns the master layout displayed in the designer.
92      * \see layout()
93      */
94     virtual QgsMasterLayoutInterface *masterLayout() = 0;
95 
96     /**
97      * Returns a pointer to the designer window.
98      *
99      * \since QGIS 3.4
100      */
101     virtual QWidget *window() = 0;
102 
103     /**
104      * Returns the layout view utilized by the designer.
105      * \see layout()
106      */
107     virtual QgsLayoutView *view() = 0;
108 
109     /**
110      * Returns the designer's message bar.
111      */
112     virtual QgsMessageBar *messageBar() = 0;
113 
114     /**
115      * Selects the specified \a items.
116      */
117     virtual void selectItems( const QList< QgsLayoutItem * > &items ) = 0;
118 
119     /**
120      * Toggles whether the atlas preview mode should be \a enabled in the designer.
121      *
122      * \see atlasPreviewEnabled()
123      * \since QGIS 3.4
124      */
125     virtual void setAtlasPreviewEnabled( bool enabled ) = 0;
126 
127     /**
128      * Returns whether the atlas preview mode is enabled in the designer.
129      *
130      * \see setAtlasPreviewEnabled()
131      * \since QGIS 3.4
132      */
133     virtual bool atlasPreviewEnabled() const = 0;
134 
135     /**
136      * Sets the specified feature as the current atlas feature
137      * \warning it is the caller's responsibility to ensure that \a feature is a feature from the layout's current atlas coverage layer.
138      * \since QGIS 3.14
139      */
140     virtual void setAtlasFeature( const QgsFeature &feature ) = 0;
141 
142     /**
143      * Shows the configuration widget for the specified layout \a item.
144      *
145      * If \a bringPanelToFront is TRUE, then the item properties panel will be automatically
146      * shown and raised to the top of the interface.
147      *
148      * \since QGIS 3.4
149      */
150     virtual void showItemOptions( QgsLayoutItem *item, bool bringPanelToFront = true ) = 0;
151 
152     // Menus and toolbars
153 
154     /**
155      * Returns a reference to the designer's "Layout" menu.
156      *
157      * \note See class documentation for notes regarding handling customization of designer dialogs.
158      *
159      * \see editMenu()
160      * \see viewMenu()
161      * \see itemsMenu()
162      * \see atlasMenu()
163      * \see reportMenu()
164      * \see settingsMenu()
165      *
166      * \since QGIS 3.4
167      */
168     virtual QMenu *layoutMenu() = 0;
169 
170     /**
171      * Returns a reference to the designer's "Edit" menu.
172      *
173      * \note See class documentation for notes regarding handling customization of designer dialogs.
174      *
175      * \see layoutMenu()
176      * \see viewMenu()
177      * \see itemsMenu()
178      * \see atlasMenu()
179      * \see reportMenu()
180      * \see settingsMenu()
181      *
182      * \since QGIS 3.4
183      */
184     virtual QMenu *editMenu() = 0;
185 
186     /**
187      * Returns a reference to the designer's "View" menu.
188      *
189      * \note See class documentation for notes regarding handling customization of designer dialogs.
190      *
191      * \see layoutMenu()
192      * \see editMenu()
193      * \see itemsMenu()
194      * \see atlasMenu()
195      * \see reportMenu()
196      * \see settingsMenu()
197      *
198      * \since QGIS 3.4
199      */
200     virtual QMenu *viewMenu() = 0;
201 
202     /**
203      * Returns a reference to the designer's "Items" menu.
204      *
205      * \note See class documentation for notes regarding handling customization of designer dialogs.
206      *
207      * \see layoutMenu()
208      * \see editMenu()
209      * \see viewMenu()
210      * \see atlasMenu()
211      * \see reportMenu()
212      * \see settingsMenu()
213      *
214      * \since QGIS 3.4
215      */
216     virtual QMenu *itemsMenu() = 0;
217 
218     /**
219      * Returns a reference to the designer's "Atlas" menu.
220      *
221      * Note that this may not exist or may be hidden if the designer is in report mode.
222      *
223      * \note See class documentation for notes regarding handling customization of designer dialogs.
224      *
225      * \see layoutMenu()
226      * \see editMenu()
227      * \see viewMenu()
228      * \see itemsMenu()
229      * \see reportMenu()
230      * \see settingsMenu()
231      *
232      * \since QGIS 3.4
233      */
234     virtual QMenu *atlasMenu() = 0;
235 
236     /**
237      * Returns a reference to the designer's "Report" menu.
238      *
239      * Note that this may not exist or may be hidden if the designer is not in report mode.
240      *
241      * \note See class documentation for notes regarding handling customization of designer dialogs.
242      *
243      * \see layoutMenu()
244      * \see editMenu()
245      * \see viewMenu()
246      * \see itemsMenu()
247      * \see atlasMenu()
248      * \see settingsMenu()
249      *
250      * \since QGIS 3.4
251      */
252     virtual QMenu *reportMenu() = 0;
253 
254     /**
255      * Returns a reference to the designer's "Settings" menu.
256      *
257      * \note See class documentation for notes regarding handling customization of designer dialogs.
258      *
259      * \see layoutMenu()
260      * \see editMenu()
261      * \see viewMenu()
262      * \see itemsMenu()
263      * \see atlasMenu()
264      * \see reportMenu()
265      *
266      * \since QGIS 3.4
267      */
268     virtual QMenu *settingsMenu() = 0;
269 
270     /**
271      * Returns a reference to the designer's "Layout" toolbar.
272      *
273      * \note See class documentation for notes regarding handling customization of designer dialogs.
274      *
275      * \see navigationToolbar()
276      * \see actionsToolbar()
277      * \see atlasToolbar()
278      *
279      * \since QGIS 3.4
280      */
281     virtual QToolBar *layoutToolbar() = 0;
282 
283     /**
284      * Returns a reference to the designer's "Navigation" toolbar.
285      *
286      * \note See class documentation for notes regarding handling customization of designer dialogs.
287      *
288      * \see layoutToolbar()
289      * \see actionsToolbar()
290      * \see atlasToolbar()
291      *
292      * \since QGIS 3.4
293      */
294     virtual QToolBar *navigationToolbar() = 0;
295 
296     /**
297      * Returns a reference to the designer's "Actions" toolbar.
298      *
299      * \note See class documentation for notes regarding handling customization of designer dialogs.
300      *
301      * \see layoutToolbar()
302      * \see navigationToolbar()
303      * \see atlasToolbar()
304      *
305      * \since QGIS 3.4
306      */
307     virtual QToolBar *actionsToolbar() = 0;
308 
309     /**
310      * Returns a reference to the designer's "Atlas" toolbar.
311      *
312      * Note that this toolbar may not exist or may be hidden if the
313      * designer is in report mode.
314      *
315      * \note See class documentation for notes regarding handling customization of designer dialogs.
316      *
317      * \see layoutToolbar()
318      * \see navigationToolbar()
319      * \see actionsToolbar()
320      *
321      * \since QGIS 3.4
322      */
323     virtual QToolBar *atlasToolbar() = 0;
324 
325     /**
326      * Adds a \a dock widget to the layout designer, in the specified dock \a area.
327      *
328      * \note See class documentation for notes regarding handling customization of designer dialogs.
329      *
330      * \see removeDockWidget()
331      *
332      * \since QGIS 3.4
333      */
334     virtual void addDockWidget( Qt::DockWidgetArea area, QDockWidget *dock ) = 0;
335 
336     /**
337      * Removes the specified \a dock widget from layout designer (without deleting it).
338      *
339      * \note See class documentation for notes regarding handling customization of designer dialogs.
340      *
341      * \see addDockWidget()
342      *
343      * \since QGIS 3.4
344      */
345     virtual void removeDockWidget( QDockWidget *dock ) = 0;
346 
347     /**
348      * Activates a standard layout designer \a tool.
349      *
350      * \since QGIS 3.6
351      */
352     virtual void activateTool( StandardTool tool ) = 0;
353 
354   public slots:
355 
356     /**
357      * Closes the layout designer.
358      */
359     virtual void close() = 0;
360 
361     /**
362      * Toggles whether or not the rulers should be \a visible in the designer.
363      *
364      * \since QGIS 3.4
365      */
366     virtual void showRulers( bool visible ) = 0;
367 
368 
369 };
370 
371 #endif // QGSLAYOUTDESIGNERINTERFACE_H
372