Skip to content

Commit

Permalink
[layouts] Add notes to layout designer dialog interface documentation
Browse files Browse the repository at this point in the history 
regarding customisation of designer instances
  • Loading branch information
@nyalldawson
nyalldawson committed Oct 22, 2018
1 parent 41f5abc commit 8a525b0
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 0 deletions.
77 changes: 77 additions & 0 deletions python/gui/auto_generated/layout/qgslayoutdesignerinterface.sip.in
View file
Expand Up @@ -18,6 +18,18 @@ Provides a common interface and stable API for layout designer dialogs and widge
This interface can be used by plugins and scripts to interact with
open layout designer dialogs.

.. note::

Layout designer dialogs are transitory. They are created only on demand
(when a user opens the dialog) and are deleted as soon as the user closes the dialog.
There can be multiple designer dialogs open at any one time, and each is a separate
instance of the dialog and QgsLayoutDesignerInterface. Accordingly, plugins must
take care to react to newly created designer dialogs and apply their customizations
to all newly created dialogs. This can be done by listening for the QgisInterface.layoutDesignerOpened
signal. Plugins must also listen for the QgisInterface.layoutDesignerWillBeClosed
signal and gracefully cleanup any customisations before the designer dialog is
deleted.

.. versionadded:: 3.0
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`editMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`settingsMenu`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutMenu`

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

.. seealso:: :py:func:`reportMenu`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`navigationToolbar`

.. seealso:: :py:func:`actionsToolbar`

.. seealso:: :py:func:`atlasToolbar`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutToolbar`

.. seealso:: :py:func:`actionsToolbar`

.. seealso:: :py:func:`atlasToolbar`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutToolbar`

.. seealso:: :py:func:`navigationToolbar`

.. seealso:: :py:func:`atlasToolbar`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`layoutToolbar`

.. seealso:: :py:func:`navigationToolbar`

.. seealso:: :py:func:`actionsToolbar`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`removeDockWidget`


.. versionadded:: 3.4
%End

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

.. note::

See class documentation for notes regarding handling customisation of designer dialogs.

.. seealso:: :py:func:`addDockWidget`


.. versionadded:: 3.4
%End

Expand Down
36 changes: 36 additions & 0 deletions src/gui/layout/qgslayoutdesignerinterface.h
View file
Expand Up @@ -38,6 +38,16 @@ class QToolBar;
* This interface can be used by plugins and scripts to interact with
* open layout designer dialogs.
*
* \note Layout designer dialogs are transitory. They are created only on demand
* (when a user opens the dialog) and are deleted as soon as the user closes the dialog.
* There can be multiple designer dialogs open at any one time, and each is a separate
* instance of the dialog and QgsLayoutDesignerInterface. Accordingly, plugins must
* take care to react to newly created designer dialogs and apply their customizations
* to all newly created dialogs. This can be done by listening for the QgisInterface::layoutDesignerOpened
* signal. Plugins must also listen for the QgisInterface::layoutDesignerWillBeClosed
* signal and gracefully cleanup any customisations before the designer dialog is
* deleted.
*
* \since QGIS 3.0
*/
class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
Expand Down Expand Up @@ -112,6 +122,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Layout" menu.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see editMenu()
* \see viewMenu()
* \see itemsMenu()
Expand All @@ -126,6 +138,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Edit" menu.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see viewMenu()
* \see itemsMenu()
Expand All @@ -140,6 +154,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "View" menu.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see editMenu()
* \see itemsMenu()
Expand All @@ -154,6 +170,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Items" menu.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see editMenu()
* \see viewMenu()
Expand All @@ -170,6 +188,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
*
* Note that this may not exist or may be hidden if the designer is in report mode.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see editMenu()
* \see viewMenu()
Expand All @@ -186,6 +206,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
*
* Note that this may not exist or may be hidden if the designer is not in report mode.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see editMenu()
* \see viewMenu()
Expand All @@ -200,6 +222,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Settings" menu.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutMenu()
* \see editMenu()
* \see viewMenu()
Expand All @@ -214,6 +238,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Layout" toolbar.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see navigationToolbar()
* \see actionsToolbar()
* \see atlasToolbar()
Expand All @@ -225,6 +251,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Navigation" toolbar.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutToolbar()
* \see actionsToolbar()
* \see atlasToolbar()
Expand All @@ -236,6 +264,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Returns a reference to the designer's "Actions" toolbar.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutToolbar()
* \see navigationToolbar()
* \see atlasToolbar()
Expand All @@ -250,6 +280,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
* Note that this toolbar may not exist or may be hidden if the
* designer is in report mode.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see layoutToolbar()
* \see navigationToolbar()
* \see actionsToolbar()
Expand All @@ -261,6 +293,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Adds a \a dock widget to the layout designer, in the specified dock \a area.
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see removeDockWidget()
*
* \since QGIS 3.4
Expand All @@ -270,6 +304,8 @@ class GUI_EXPORT QgsLayoutDesignerInterface: public QObject
/**
* Removes the specified \a dock widget from layout designer (without deleting it).
*
* \note See class documentation for notes regarding handling customisation of designer dialogs.
*
* \see addDockWidget()
*
* \since QGIS 3.4
Expand Down

0 comments on commit 8a525b0

Please sign in to comment.