From c92d7dc39b9ec7551c90cdac21b3ae2e6ff11d7a Mon Sep 17 00:00:00 2001 From: Martin Dobias Date: Fri, 15 Sep 2017 16:44:42 +0200 Subject: [PATCH] Docstring/sip fixes in core/3d --- python/CMakeLists.txt | 1 + python/core/3d/qgs3drendererregistry.sip | 96 ++++++++++++++++++++++++ python/core/3d/qgsabstract3drenderer.sip | 68 +++++++++++++++++ python/core/core_auto.sip | 2 + python/core/qgsapplication.sip | 9 +++ python/core/qgsmaplayer.sip | 17 +++++ scripts/spell_check/check_spelling.sh | 2 +- src/core/3d/qgs3drendererregistry.cpp | 22 +++--- src/core/3d/qgs3drendererregistry.h | 46 +++++++++--- src/core/3d/qgsabstract3drenderer.h | 27 +++++-- src/core/qgsapplication.h | 2 +- src/core/qgsmaplayer.h | 4 +- 12 files changed, 266 insertions(+), 30 deletions(-) create mode 100644 python/core/3d/qgs3drendererregistry.sip create mode 100644 python/core/3d/qgsabstract3drenderer.sip diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt index 5893f9f5ed3..28c7b91f394 100755 --- a/python/CMakeLists.txt +++ b/python/CMakeLists.txt @@ -102,6 +102,7 @@ ENDIF () INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/src/core + ${CMAKE_SOURCE_DIR}/src/core/3d ${CMAKE_SOURCE_DIR}/src/core/annotations ${CMAKE_SOURCE_DIR}/src/core/auth ${CMAKE_SOURCE_DIR}/src/core/expression diff --git a/python/core/3d/qgs3drendererregistry.sip b/python/core/3d/qgs3drendererregistry.sip new file mode 100644 index 00000000000..6fda0688095 --- /dev/null +++ b/python/core/3d/qgs3drendererregistry.sip @@ -0,0 +1,96 @@ +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/3d/qgs3drendererregistry.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + + +class Qgs3DRendererAbstractMetadata +{ +%Docstring + Base metadata class for 3D renderers. Instances of derived classes may be registered in Qgs3DRendererRegistry. +.. versionadded:: 3.0 +%End + +%TypeHeaderCode +#include "qgs3drendererregistry.h" +%End + public: + + virtual ~Qgs3DRendererAbstractMetadata(); + + QString type() const; +%Docstring + Returns unique identifier of the 3D renderer class + :rtype: str +%End + + virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0 /Factory/; +%Docstring + Returns new instance of the renderer given the DOM element. Returns NULL on error. + Pure virtual function: must be implemented in derived classes. + :rtype: QgsAbstract3DRenderer +%End + + protected: + + explicit Qgs3DRendererAbstractMetadata( const QString &type ); +%Docstring + Constructor of the base class +%End + + protected: +}; + + +class Qgs3DRendererRegistry +{ +%Docstring + Keeps track of available 3D renderers. Should be accessed through QgsApplication.renderer3DRegistry() singleton. +.. versionadded:: 3.0 +%End + +%TypeHeaderCode +#include "qgs3drendererregistry.h" +%End + public: + Qgs3DRendererRegistry(); + + ~Qgs3DRendererRegistry(); + + void addRenderer( Qgs3DRendererAbstractMetadata *metadata /Transfer/ ); +%Docstring + Registers a new 3D renderer type. The call takes ownership of the passed metadata object. +%End + + void removeRenderer( const QString &type ); +%Docstring + Unregisters a 3D renderer type +%End + + Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &type ) const; +%Docstring + Returns metadata for a 3D renderer type (may be used to create a new instance of the type) + :rtype: Qgs3DRendererAbstractMetadata +%End + + QStringList renderersList() const; +%Docstring + Returns a list of all available 3D renderer types. + :rtype: list of str +%End + +}; + +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/3d/qgs3drendererregistry.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/python/core/3d/qgsabstract3drenderer.sip b/python/core/3d/qgsabstract3drenderer.sip new file mode 100644 index 00000000000..cc52e19e202 --- /dev/null +++ b/python/core/3d/qgsabstract3drenderer.sip @@ -0,0 +1,68 @@ +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/3d/qgsabstract3drenderer.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ + + + + +namespace Qt3DCore +{ +} + +class QgsAbstract3DRenderer +{ +%Docstring + Base class for all renderers that may to participate in 3D view. + + 3D renderers implement the method createEntity() that returns a new 3D entity - that entity + will be added to the 3D scene to represent data in renderer's display style. + + Renderers may store some custom properties (e.g. materials, sizes) that are written to and read from + XML. It is therefore not recommended to store large amount of data within a renderer (e.g. arrays of vertices). + +.. versionadded:: 3.0 +%End + +%TypeHeaderCode +#include "qgsabstract3drenderer.h" +%End + public: + virtual ~QgsAbstract3DRenderer(); + + virtual QString type() const = 0; +%Docstring +Returns unique identifier of the renderer class (used to identify subclass) + :rtype: str +%End + virtual QgsAbstract3DRenderer *clone() const = 0 /Factory/; +%Docstring +Returns a cloned instance + :rtype: QgsAbstract3DRenderer +%End + + virtual void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const = 0; +%Docstring +Writes renderer's properties to given XML element +%End + virtual void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) = 0; +%Docstring +Reads renderer's properties from given XML element +%End + virtual void resolveReferences( const QgsProject &project ); +%Docstring +Resolves references to other objects - second phase of loading - after readXml() +%End +}; + + +/************************************************************************ + * This file has been generated automatically from * + * * + * src/core/3d/qgsabstract3drenderer.h * + * * + * Do not edit manually ! Edit header and run scripts/sipify.pl again * + ************************************************************************/ diff --git a/python/core/core_auto.sip b/python/core/core_auto.sip index 8ee5455772b..b2c480c13ca 100644 --- a/python/core/core_auto.sip +++ b/python/core/core_auto.sip @@ -279,6 +279,8 @@ %Include geometry/qgssurface.sip %Include geometry/qgswkbptr.sip %Include geometry/qgswkbtypes.sip +%Include 3d/qgs3drendererregistry.sip +%Include 3d/qgsabstract3drenderer.sip %Include fieldformatter/qgsdatetimefieldformatter.sip %Include fieldformatter/qgsfallbackfieldformatter.sip %Include fieldformatter/qgskeyvaluefieldformatter.sip diff --git a/python/core/qgsapplication.sip b/python/core/qgsapplication.sip index 17aa06c84d2..efa07c61106 100644 --- a/python/core/qgsapplication.sip +++ b/python/core/qgsapplication.sip @@ -704,6 +704,15 @@ Returns path to the build output directory. Valid only when running from build d :rtype: QgsFieldFormatterRegistry %End + static Qgs3DRendererRegistry *renderer3DRegistry(); +%Docstring + Returns registry of available 3D renderers. +.. note:: + + not available in Python bindings +.. versionadded:: 3.0 + :rtype: Qgs3DRendererRegistry +%End static QString nullRepresentation(); %Docstring diff --git a/python/core/qgsmaplayer.sip b/python/core/qgsmaplayer.sip index 6e2fc4b9e74..ed3b5962642 100644 --- a/python/core/qgsmaplayer.sip +++ b/python/core/qgsmaplayer.sip @@ -760,7 +760,24 @@ Return pointer to layer's undo stack :rtype: QgsMapLayerStyleManager %End + void setRenderer3D( QgsAbstract3DRenderer *renderer /Transfer/ ); +%Docstring + Sets 3D renderer for the layer. Takes ownership of the renderer. +.. note:: + not available in Python bindings +.. versionadded:: 3.0 +%End + + QgsAbstract3DRenderer *renderer3D() const; +%Docstring + Returns 3D renderer associated with the layer. May be null. +.. note:: + + not available in Python bindings +.. versionadded:: 3.0 + :rtype: QgsAbstract3DRenderer +%End bool isInScaleRange( double scale ) const; %Docstring diff --git a/scripts/spell_check/check_spelling.sh b/scripts/spell_check/check_spelling.sh index 132098ec182..2a62a760d40 100755 --- a/scripts/spell_check/check_spelling.sh +++ b/scripts/spell_check/check_spelling.sh @@ -23,7 +23,7 @@ # fi # extensions or files that should be excluded from file list if :% is appended in the spelling.dat file -EXCLUDE_SCRIPT_LIST='(\.(xml|svg|sip|t2t|pl|sh|qgs|badquote|cmake(\.in)?)|^(debian/copyright|cmake_templates/.*|INSTALL|NEWS|tests/testdata/labeling/README.rst|tests/testdata/font/QGIS-Vera/COPYRIGHT.TXT|doc/(news|INSTALL)\.html))$' +EXCLUDE_SCRIPT_LIST='(\.(xml|svg|sip|t2t|pl|sh|qgs|badquote|cmake(\.in)?)|^(debian/copyright|cmake_templates/.*|INSTALL|NEWS|tests/testdata/labeling/README.rst|tests/testdata/font/QGIS-Vera/COPYRIGHT.TXT|doc/(news|INSTALL)\.html)|src/3d/poly2tri/.*)$' DIR=$(git rev-parse --show-toplevel)/scripts/spell_check diff --git a/src/core/3d/qgs3drendererregistry.cpp b/src/core/3d/qgs3drendererregistry.cpp index 355a0df146f..972a2ee8b98 100644 --- a/src/core/3d/qgs3drendererregistry.cpp +++ b/src/core/3d/qgs3drendererregistry.cpp @@ -1,14 +1,18 @@ #include "qgs3drendererregistry.h" -Qgs3DRendererAbstractMetadata::Qgs3DRendererAbstractMetadata( const QString &name ) - : mName( name ) +Qgs3DRendererAbstractMetadata::Qgs3DRendererAbstractMetadata( const QString &type ) + : mType( type ) { } -QString Qgs3DRendererAbstractMetadata::name() const +Qgs3DRendererAbstractMetadata::~Qgs3DRendererAbstractMetadata() { - return mName; +} + +QString Qgs3DRendererAbstractMetadata::type() const +{ + return mType; } @@ -26,17 +30,17 @@ Qgs3DRendererRegistry::~Qgs3DRendererRegistry() void Qgs3DRendererRegistry::addRenderer( Qgs3DRendererAbstractMetadata *metadata ) { - mRenderers.insert( metadata->name(), metadata ); + mRenderers.insert( metadata->type(), metadata ); } -void Qgs3DRendererRegistry::removeRenderer( const QString &name ) +void Qgs3DRendererRegistry::removeRenderer( const QString &type ) { - delete mRenderers.take( name ); + delete mRenderers.take( type ); } -Qgs3DRendererAbstractMetadata *Qgs3DRendererRegistry::rendererMetadata( const QString &name ) const +Qgs3DRendererAbstractMetadata *Qgs3DRendererRegistry::rendererMetadata( const QString &type ) const { - return mRenderers.value( name ); + return mRenderers.value( type ); } QStringList Qgs3DRendererRegistry::renderersList() const diff --git a/src/core/3d/qgs3drendererregistry.h b/src/core/3d/qgs3drendererregistry.h index 03eaf1efb79..52a2433e54e 100644 --- a/src/core/3d/qgs3drendererregistry.h +++ b/src/core/3d/qgs3drendererregistry.h @@ -2,6 +2,7 @@ #define QGS3DRENDERERREGISTRY_H #include "qgis_core.h" +#include "qgis_sip.h" #include @@ -19,17 +20,29 @@ class CORE_EXPORT Qgs3DRendererAbstractMetadata { public: - Qgs3DRendererAbstractMetadata( const QString &name ); + virtual ~Qgs3DRendererAbstractMetadata(); - QString name() const; + /** + * Returns unique identifier of the 3D renderer class + */ + QString type() const; - /** Return new instance of the renderer given the DOM element. Returns NULL on error. - * Pure virtual function: must be implemented in derived classes. */ - virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0; + /** + * Returns new instance of the renderer given the DOM element. Returns NULL on error. + * Pure virtual function: must be implemented in derived classes. + */ + virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0 SIP_FACTORY; protected: - //! name used within QGIS for identification (the same what renderer's type() returns) - QString mName; + + /** + * Constructor of the base class + */ + explicit Qgs3DRendererAbstractMetadata( const QString &type ); + + protected: + //! Type used within QGIS for identification (the same what renderer's type() returns) + QString mType; }; @@ -45,13 +58,24 @@ class CORE_EXPORT Qgs3DRendererRegistry ~Qgs3DRendererRegistry(); - //! takes ownership - void addRenderer( Qgs3DRendererAbstractMetadata *metadata ); + /** + * Registers a new 3D renderer type. The call takes ownership of the passed metadata object. + */ + void addRenderer( Qgs3DRendererAbstractMetadata *metadata SIP_TRANSFER ); - void removeRenderer( const QString &name ); + /** + * Unregisters a 3D renderer type + */ + void removeRenderer( const QString &type ); - Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &name ) const; + /** + * Returns metadata for a 3D renderer type (may be used to create a new instance of the type) + */ + Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &type ) const; + /** + * Returns a list of all available 3D renderer types. + */ QStringList renderersList() const; private: diff --git a/src/core/3d/qgsabstract3drenderer.h b/src/core/3d/qgsabstract3drenderer.h index 21ef014769a..6c861eeddd0 100644 --- a/src/core/3d/qgsabstract3drenderer.h +++ b/src/core/3d/qgsabstract3drenderer.h @@ -2,6 +2,7 @@ #define QGSABSTRACT3DRENDERER_H #include "qgis_core.h" +#include "qgis_sip.h" #include @@ -15,22 +16,36 @@ namespace Qt3DCore class QEntity; } -//! Base class for all renderers that may to participate in 3D view. -class CORE_EXPORT QgsAbstract3DRenderer //: public QObject +/** \ingroup core + * Base class for all renderers that may to participate in 3D view. + * + * 3D renderers implement the method createEntity() that returns a new 3D entity - that entity + * will be added to the 3D scene to represent data in renderer's display style. + * + * Renderers may store some custom properties (e.g. materials, sizes) that are written to and read from + * XML. It is therefore not recommended to store large amount of data within a renderer (e.g. arrays of vertices). + * + * \since QGIS 3.0 + */ +class CORE_EXPORT QgsAbstract3DRenderer { - //Q_OBJECT public: virtual ~QgsAbstract3DRenderer(); + //! Returns unique identifier of the renderer class (used to identify subclass) virtual QString type() const = 0; - virtual QgsAbstract3DRenderer *clone() const = 0; - virtual Qt3DCore::QEntity *createEntity( const Qgs3DMapSettings &map ) const = 0; + //! Returns a cloned instance + virtual QgsAbstract3DRenderer *clone() const = 0 SIP_FACTORY; + //! Returns a 3D entity that will be used to show renderer's data in 3D scene + virtual Qt3DCore::QEntity *createEntity( const Qgs3DMapSettings &map ) const = 0 SIP_SKIP; + //! Writes renderer's properties to given XML element virtual void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const = 0; + //! Reads renderer's properties from given XML element virtual void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) = 0; + //! Resolves references to other objects - second phase of loading - after readXml() virtual void resolveReferences( const QgsProject &project ); }; - #endif // QGSABSTRACT3DRENDERER_H diff --git a/src/core/qgsapplication.h b/src/core/qgsapplication.h index 5b935c88f38..00c040dd13e 100644 --- a/src/core/qgsapplication.h +++ b/src/core/qgsapplication.h @@ -589,7 +589,7 @@ class CORE_EXPORT QgsApplication : public QApplication * \note not available in Python bindings * \since QGIS 3.0 */ - static Qgs3DRendererRegistry *renderer3DRegistry() SIP_SKIP; + static Qgs3DRendererRegistry *renderer3DRegistry(); /** * This string is used to represent the value `NULL` throughout QGIS. diff --git a/src/core/qgsmaplayer.h b/src/core/qgsmaplayer.h index 6dc11d62ede..cc1d5d4c4fe 100644 --- a/src/core/qgsmaplayer.h +++ b/src/core/qgsmaplayer.h @@ -686,14 +686,14 @@ class CORE_EXPORT QgsMapLayer : public QObject * \note not available in Python bindings * \since QGIS 3.0 */ - void setRenderer3D( QgsAbstract3DRenderer *renderer SIP_TRANSFER ) SIP_SKIP; + void setRenderer3D( QgsAbstract3DRenderer *renderer SIP_TRANSFER ); /** * Returns 3D renderer associated with the layer. May be null. * \note not available in Python bindings * \since QGIS 3.0 */ - QgsAbstract3DRenderer *renderer3D() const SIP_SKIP; + QgsAbstract3DRenderer *renderer3D() const; /** Tests whether the layer should be visible at the specified \a scale. * The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.