Skip to content
Permalink
Browse files

[layouts] Add notes to layout designer dialog interface documentation

regarding customisation of designer instances
  • Loading branch information
nyalldawson committed Oct 22, 2018
1 parent 41f5abc commit 8a525b0b86fbfdbcbb18331391e6aee498e5d87a
@@ -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

@@ -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`
@@ -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`
@@ -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`
@@ -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`
@@ -164,6 +195,7 @@ Returns a reference to the designer's "Items" menu.

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


.. versionadded:: 3.4
%End

@@ -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`
@@ -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

@@ -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`
@@ -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`
@@ -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

@@ -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

@@ -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
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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()
@@ -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
@@ -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

0 comments on commit 8a525b0

Please sign in to comment.
You can’t perform that action at this time.