Skip to content

Commit 8a525b0

Browse files
nyalldawsonnyalldawson
committedOct 22, 2018
[layouts] Add notes to layout designer dialog interface documentation
regarding customisation of designer instances
·
ltr-3_40final-3_4_0
1 parent 41f5abc commit 8a525b0

File tree

2 files changed

+113
-0
lines changed

2 files changed

+113
-0
lines changed
 

‎python/gui/auto_generated/layout/qgslayoutdesignerinterface.sip.in

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,18 @@ Provides a common interface and stable API for layout designer dialogs and widge
1818
This interface can be used by plugins and scripts to interact with
1919
open layout designer dialogs.
2020

21+
.. note::
22+
23+
Layout designer dialogs are transitory. They are created only on demand
24+
(when a user opens the dialog) and are deleted as soon as the user closes the dialog.
25+
There can be multiple designer dialogs open at any one time, and each is a separate
26+
instance of the dialog and QgsLayoutDesignerInterface. Accordingly, plugins must
27+
take care to react to newly created designer dialogs and apply their customizations
28+
to all newly created dialogs. This can be done by listening for the QgisInterface.layoutDesignerOpened
29+
signal. Plugins must also listen for the QgisInterface.layoutDesignerWillBeClosed
30+
signal and gracefully cleanup any customisations before the designer dialog is
31+
deleted.
32+
2133
.. versionadded:: 3.0
2234
%End
2335

@@ -95,6 +107,10 @@ shown and raised to the top of the interface.
95107
%Docstring
96108
Returns a reference to the designer's "Layout" menu.
97109

110+
.. note::
111+
112+
See class documentation for notes regarding handling customisation of designer dialogs.
113+
98114
.. seealso:: :py:func:`editMenu`
99115

100116
.. seealso:: :py:func:`viewMenu`
@@ -107,13 +123,18 @@ Returns a reference to the designer's "Layout" menu.
107123

108124
.. seealso:: :py:func:`settingsMenu`
109125

126+
110127
.. versionadded:: 3.4
111128
%End
112129

113130
virtual QMenu *editMenu() = 0;
114131
%Docstring
115132
Returns a reference to the designer's "Edit" menu.
116133

134+
.. note::
135+
136+
See class documentation for notes regarding handling customisation of designer dialogs.
137+
117138
.. seealso:: :py:func:`layoutMenu`
118139

119140
.. seealso:: :py:func:`viewMenu`
@@ -126,13 +147,18 @@ Returns a reference to the designer's "Edit" menu.
126147

127148
.. seealso:: :py:func:`settingsMenu`
128149

150+
129151
.. versionadded:: 3.4
130152
%End
131153

132154
virtual QMenu *viewMenu() = 0;
133155
%Docstring
134156
Returns a reference to the designer's "View" menu.
135157

158+
.. note::
159+
160+
See class documentation for notes regarding handling customisation of designer dialogs.
161+
136162
.. seealso:: :py:func:`layoutMenu`
137163

138164
.. seealso:: :py:func:`editMenu`
@@ -145,13 +171,18 @@ Returns a reference to the designer's "View" menu.
145171

146172
.. seealso:: :py:func:`settingsMenu`
147173

174+
148175
.. versionadded:: 3.4
149176
%End
150177

151178
virtual QMenu *itemsMenu() = 0;
152179
%Docstring
153180
Returns a reference to the designer's "Items" menu.
154181

182+
.. note::
183+
184+
See class documentation for notes regarding handling customisation of designer dialogs.
185+
155186
.. seealso:: :py:func:`layoutMenu`
156187

157188
.. seealso:: :py:func:`editMenu`
@@ -164,6 +195,7 @@ Returns a reference to the designer's "Items" menu.
164195

165196
.. seealso:: :py:func:`settingsMenu`
166197

198+
167199
.. versionadded:: 3.4
168200
%End
169201

@@ -173,6 +205,10 @@ Returns a reference to the designer's "Atlas" menu.
173205

174206
Note that this may not exist or may be hidden if the designer is in report mode.
175207

208+
.. note::
209+
210+
See class documentation for notes regarding handling customisation of designer dialogs.
211+
176212
.. seealso:: :py:func:`layoutMenu`
177213

178214
.. seealso:: :py:func:`editMenu`
@@ -185,6 +221,7 @@ Note that this may not exist or may be hidden if the designer is in report mode.
185221

186222
.. seealso:: :py:func:`settingsMenu`
187223

224+
188225
.. versionadded:: 3.4
189226
%End
190227

@@ -194,6 +231,10 @@ Returns a reference to the designer's "Report" menu.
194231

195232
Note that this may not exist or may be hidden if the designer is not in report mode.
196233

234+
.. note::
235+
236+
See class documentation for notes regarding handling customisation of designer dialogs.
237+
197238
.. seealso:: :py:func:`layoutMenu`
198239

199240
.. seealso:: :py:func:`editMenu`
@@ -206,13 +247,18 @@ Note that this may not exist or may be hidden if the designer is not in report m
206247

207248
.. seealso:: :py:func:`settingsMenu`
208249

250+
209251
.. versionadded:: 3.4
210252
%End
211253

212254
virtual QMenu *settingsMenu() = 0;
213255
%Docstring
214256
Returns a reference to the designer's "Settings" menu.
215257

258+
.. note::
259+
260+
See class documentation for notes regarding handling customisation of designer dialogs.
261+
216262
.. seealso:: :py:func:`layoutMenu`
217263

218264
.. seealso:: :py:func:`editMenu`
@@ -225,45 +271,61 @@ Returns a reference to the designer's "Settings" menu.
225271

226272
.. seealso:: :py:func:`reportMenu`
227273

274+
228275
.. versionadded:: 3.4
229276
%End
230277

231278
virtual QToolBar *layoutToolbar() = 0;
232279
%Docstring
233280
Returns a reference to the designer's "Layout" toolbar.
234281

282+
.. note::
283+
284+
See class documentation for notes regarding handling customisation of designer dialogs.
285+
235286
.. seealso:: :py:func:`navigationToolbar`
236287

237288
.. seealso:: :py:func:`actionsToolbar`
238289

239290
.. seealso:: :py:func:`atlasToolbar`
240291

292+
241293
.. versionadded:: 3.4
242294
%End
243295

244296
virtual QToolBar *navigationToolbar() = 0;
245297
%Docstring
246298
Returns a reference to the designer's "Navigation" toolbar.
247299

300+
.. note::
301+
302+
See class documentation for notes regarding handling customisation of designer dialogs.
303+
248304
.. seealso:: :py:func:`layoutToolbar`
249305

250306
.. seealso:: :py:func:`actionsToolbar`
251307

252308
.. seealso:: :py:func:`atlasToolbar`
253309

310+
254311
.. versionadded:: 3.4
255312
%End
256313

257314
virtual QToolBar *actionsToolbar() = 0;
258315
%Docstring
259316
Returns a reference to the designer's "Actions" toolbar.
260317

318+
.. note::
319+
320+
See class documentation for notes regarding handling customisation of designer dialogs.
321+
261322
.. seealso:: :py:func:`layoutToolbar`
262323

263324
.. seealso:: :py:func:`navigationToolbar`
264325

265326
.. seealso:: :py:func:`atlasToolbar`
266327

328+
267329
.. versionadded:: 3.4
268330
%End
269331

@@ -274,30 +336,45 @@ Returns a reference to the designer's "Atlas" toolbar.
274336
Note that this toolbar may not exist or may be hidden if the
275337
designer is in report mode.
276338

339+
.. note::
340+
341+
See class documentation for notes regarding handling customisation of designer dialogs.
342+
277343
.. seealso:: :py:func:`layoutToolbar`
278344

279345
.. seealso:: :py:func:`navigationToolbar`
280346

281347
.. seealso:: :py:func:`actionsToolbar`
282348

349+
283350
.. versionadded:: 3.4
284351
%End
285352

286353
virtual void addDockWidget( Qt::DockWidgetArea area, QDockWidget *dock ) = 0;
287354
%Docstring
288355
Adds a ``dock`` widget to the layout designer, in the specified dock ``area``.
289356

357+
.. note::
358+
359+
See class documentation for notes regarding handling customisation of designer dialogs.
360+
290361
.. seealso:: :py:func:`removeDockWidget`
291362

363+
292364
.. versionadded:: 3.4
293365
%End
294366

295367
virtual void removeDockWidget( QDockWidget *dock ) = 0;
296368
%Docstring
297369
Removes the specified ``dock`` widget from layout designer (without deleting it).
298370

371+
.. note::
372+
373+
See class documentation for notes regarding handling customisation of designer dialogs.
374+
299375
.. seealso:: :py:func:`addDockWidget`
300376

377+
301378
.. versionadded:: 3.4
302379
%End
303380

‎src/gui/layout/qgslayoutdesignerinterface.h

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,16 @@ class QToolBar;
3838
* This interface can be used by plugins and scripts to interact with
3939
* open layout designer dialogs.
4040
*
41+
* \note Layout designer dialogs are transitory. They are created only on demand
42+
* (when a user opens the dialog) and are deleted as soon as the user closes the dialog.
43+
* There can be multiple designer dialogs open at any one time, and each is a separate
44+
* instance of the dialog and QgsLayoutDesignerInterface. Accordingly, plugins must
45+
* take care to react to newly created designer dialogs and apply their customizations
46+
* to all newly created dialogs. This can be done by listening for the QgisInterface::layoutDesignerOpened
47+
* signal. Plugins must also listen for the QgisInterface::layoutDesignerWillBeClosed
48+
* signal and gracefully cleanup any customisations before the designer dialog is
49+
* deleted.
50+
*
4151
* \since QGIS 3.0
4252
*/
4353
class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
@@ -112,6 +122,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
112122
/**
113123
* Returns a reference to the designer's "Layout" menu.
114124
*
125+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
126+
*
115127
* \see editMenu()
116128
* \see viewMenu()
117129
* \see itemsMenu()
@@ -126,6 +138,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
126138
/**
127139
* Returns a reference to the designer's "Edit" menu.
128140
*
141+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
142+
*
129143
* \see layoutMenu()
130144
* \see viewMenu()
131145
* \see itemsMenu()
@@ -140,6 +154,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
140154
/**
141155
* Returns a reference to the designer's "View" menu.
142156
*
157+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
158+
*
143159
* \see layoutMenu()
144160
* \see editMenu()
145161
* \see itemsMenu()
@@ -154,6 +170,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
154170
/**
155171
* Returns a reference to the designer's "Items" menu.
156172
*
173+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
174+
*
157175
* \see layoutMenu()
158176
* \see editMenu()
159177
* \see viewMenu()
@@ -170,6 +188,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
170188
*
171189
* Note that this may not exist or may be hidden if the designer is in report mode.
172190
*
191+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
192+
*
173193
* \see layoutMenu()
174194
* \see editMenu()
175195
* \see viewMenu()
@@ -186,6 +206,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
186206
*
187207
* Note that this may not exist or may be hidden if the designer is not in report mode.
188208
*
209+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
210+
*
189211
* \see layoutMenu()
190212
* \see editMenu()
191213
* \see viewMenu()
@@ -200,6 +222,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
200222
/**
201223
* Returns a reference to the designer's "Settings" menu.
202224
*
225+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
226+
*
203227
* \see layoutMenu()
204228
* \see editMenu()
205229
* \see viewMenu()
@@ -214,6 +238,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
214238
/**
215239
* Returns a reference to the designer's "Layout" toolbar.
216240
*
241+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
242+
*
217243
* \see navigationToolbar()
218244
* \see actionsToolbar()
219245
* \see atlasToolbar()
@@ -225,6 +251,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
225251
/**
226252
* Returns a reference to the designer's "Navigation" toolbar.
227253
*
254+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
255+
*
228256
* \see layoutToolbar()
229257
* \see actionsToolbar()
230258
* \see atlasToolbar()
@@ -236,6 +264,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
236264
/**
237265
* Returns a reference to the designer's "Actions" toolbar.
238266
*
267+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
268+
*
239269
* \see layoutToolbar()
240270
* \see navigationToolbar()
241271
* \see atlasToolbar()
@@ -250,6 +280,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
250280
* Note that this toolbar may not exist or may be hidden if the
251281
* designer is in report mode.
252282
*
283+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
284+
*
253285
* \see layoutToolbar()
254286
* \see navigationToolbar()
255287
* \see actionsToolbar()
@@ -261,6 +293,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
261293
/**
262294
* Adds a \a dock widget to the layout designer, in the specified dock \a area.
263295
*
296+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
297+
*
264298
* \see removeDockWidget()
265299
*
266300
* \since QGIS 3.4
@@ -270,6 +304,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
270304
/**
271305
* Removes the specified \a dock widget from layout designer (without deleting it).
272306
*
307+
* \note See class documentation for notes regarding handling customisation of designer dialogs.
308+
*
273309
* \see addDockWidget()
274310
*
275311
* \since QGIS 3.4

0 commit comments

Comments
 (0)
Please sign in to comment.