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