From 79f2f8a4123de5ae98e2773241d3f07c287ba5df Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Tue, 3 Sep 2024 08:58:29 +1000 Subject: [PATCH] Cleanup some CPT city docs --- .../core/auto_additions/qgscptcityarchive.py | 4 + .../symbology/qgscptcityarchive.sip.in | 101 ++++++++++++++++- .../core/auto_additions/qgscptcityarchive.py | 4 + .../symbology/qgscptcityarchive.sip.in | 101 ++++++++++++++++- src/core/symbology/qgscptcityarchive.h | 105 +++++++++++++++--- 5 files changed, 289 insertions(+), 26 deletions(-) diff --git a/python/PyQt6/core/auto_additions/qgscptcityarchive.py b/python/PyQt6/core/auto_additions/qgscptcityarchive.py index d0c6d9d97db..e08210f7c80 100644 --- a/python/PyQt6/core/auto_additions/qgscptcityarchive.py +++ b/python/PyQt6/core/auto_additions/qgscptcityarchive.py @@ -7,6 +7,10 @@ QgsCptCityDataItem.AllRamps = QgsCptCityDataItem.Type.AllRamps QgsCptCityBrowserModel.Authors = QgsCptCityBrowserModel.ViewType.Authors QgsCptCityBrowserModel.Selections = QgsCptCityBrowserModel.ViewType.Selections QgsCptCityBrowserModel.List = QgsCptCityBrowserModel.ViewType.List +try: + QgsCptCityDataItem.__attribute_docs__ = {'beginInsertItems': 'Emitted before child items are added to this item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.\n\n:param parent: the parent item having children added\n:param first: index of first child item to be added\n:param last: index last child item, after the addition has occurred\n\n.. seealso:: :py:func:`endInsertItems`\n', 'endInsertItems': 'Emitted after child items have been added to this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.\n\n.. seealso:: :py:func:`beginInsertItems`\n', 'beginRemoveItems': 'Emitted before child items are removed from this data item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.\n\n:param parent: the parent item having children removed\n:param first: index of first child item to be removed\n:param last: index of the last child item to be removed\n\n.. seealso:: :py:func:`endRemoveItems`\n', 'endRemoveItems': 'Emitted after child items have been removed from this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.\n\n.. seealso:: :py:func:`beginRemoveItems`\n'} +except NameError: + pass QgsCptCityArchive.defaultBaseDir = staticmethod(QgsCptCityArchive.defaultBaseDir) QgsCptCityArchive.findFileName = staticmethod(QgsCptCityArchive.findFileName) QgsCptCityArchive.copyingInfo = staticmethod(QgsCptCityArchive.copyingInfo) diff --git a/python/PyQt6/core/auto_generated/symbology/qgscptcityarchive.sip.in b/python/PyQt6/core/auto_generated/symbology/qgscptcityarchive.sip.in index 95e31cd3056..d1acde60d47 100644 --- a/python/PyQt6/core/auto_generated/symbology/qgscptcityarchive.sip.in +++ b/python/PyQt6/core/auto_generated/symbology/qgscptcityarchive.sip.in @@ -78,32 +78,85 @@ Base class for all items in the model bool hasChildren(); int rowCount(); + virtual int leafCount() const; +%Docstring +Returns the total count of "leaf" items (all children which are end nodes). +%End virtual void refresh(); virtual QVector createChildren(); +%Docstring +Returns a vector of children items. +%End virtual void populate(); +%Docstring +Populates children using children vector created by :py:func:`~QgsCptCityDataItem.createChildren`. +%End + bool isPopulated(); +%Docstring +Returns ``True`` if the item is already populated. +%End virtual void addChildItem( QgsCptCityDataItem *child /Transfer/, bool refresh = false ); +%Docstring +Inserts a new ``child`` using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals. + +The ``refresh`` argument will refresh the populated item by emitting signals to the model. +%End virtual void deleteChildItem( QgsCptCityDataItem *child ); +%Docstring +Removes and deletes a child ``item``, signals to browser are emitted. +%End virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) /TransferBack/; +%Docstring +Removes a ``child`` item but doesn't delete it, signals to browser are emitted. + +:return: pointer to the removed item or ``None`` if no such item was found +%End virtual bool equal( const QgsCptCityDataItem *other ); +%Docstring +Returns ``True`` if this item is equal to an ``other`` item. +%End - virtual QWidget *paramWidget() /Factory/; + virtual QWidget *paramWidget() /Deprecated/; +%Docstring - virtual bool acceptDrop(); +.. deprecated:: 3.40 - virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ ); + Is unused and will be removed in QGIS 4.0. +%End + + virtual bool acceptDrop() /Deprecated/; +%Docstring +Returns ``True`` if the item accepts drag & dropped layers - e.g. for import. + +.. deprecated:: 3.40 + + Is unused and will be removed in QGIS 4.0. +%End + + virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) /Deprecated/; +%Docstring +Tries to process the ``data`` dropped on this item. + +.. deprecated:: 3.40 + + Is unused and will be removed in QGIS 4.0. +%End static int findItem( QVector items, QgsCptCityDataItem *item ); +%Docstring +Finds a child index in vector of items using '==' operator. +%End Type type() const; @@ -128,10 +181,50 @@ Base class for all items in the model signals: + void beginInsertItems( QgsCptCityDataItem *parent, int first, int last ); +%Docstring +Emitted before child items are added to this item. + +This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`. + +:param parent: the parent item having children added +:param first: index of first child item to be added +:param last: index last child item, after the addition has occurred + +.. seealso:: :py:func:`endInsertItems` +%End + void endInsertItems(); +%Docstring +Emitted after child items have been added to this data item. + +This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`. + +.. seealso:: :py:func:`beginInsertItems` +%End + void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last ); +%Docstring +Emitted before child items are removed from this data item. + +This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`. + +:param parent: the parent item having children removed +:param first: index of first child item to be removed +:param last: index of the last child item to be removed + +.. seealso:: :py:func:`endRemoveItems` +%End + void endRemoveItems(); +%Docstring +Emitted after child items have been removed from this data item. + +This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`. + +.. seealso:: :py:func:`beginRemoveItems` +%End }; class QgsCptCityColorRampItem : QgsCptCityDataItem @@ -331,8 +424,6 @@ Returns index of a path virtual void fetchMore( const QModelIndex &parent ); - signals: - public slots: void beginInsertItems( QgsCptCityDataItem *parent, int first, int last ); diff --git a/python/core/auto_additions/qgscptcityarchive.py b/python/core/auto_additions/qgscptcityarchive.py index 36cd4ada664..3d417def4cd 100644 --- a/python/core/auto_additions/qgscptcityarchive.py +++ b/python/core/auto_additions/qgscptcityarchive.py @@ -1,4 +1,8 @@ # The following has been generated automatically from src/core/symbology/qgscptcityarchive.h +try: + QgsCptCityDataItem.__attribute_docs__ = {'beginInsertItems': 'Emitted before child items are added to this item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.\n\n:param parent: the parent item having children added\n:param first: index of first child item to be added\n:param last: index last child item, after the addition has occurred\n\n.. seealso:: :py:func:`endInsertItems`\n', 'endInsertItems': 'Emitted after child items have been added to this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.\n\n.. seealso:: :py:func:`beginInsertItems`\n', 'beginRemoveItems': 'Emitted before child items are removed from this data item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.\n\n:param parent: the parent item having children removed\n:param first: index of first child item to be removed\n:param last: index of the last child item to be removed\n\n.. seealso:: :py:func:`endRemoveItems`\n', 'endRemoveItems': 'Emitted after child items have been removed from this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.\n\n.. seealso:: :py:func:`beginRemoveItems`\n'} +except NameError: + pass QgsCptCityArchive.defaultBaseDir = staticmethod(QgsCptCityArchive.defaultBaseDir) QgsCptCityArchive.findFileName = staticmethod(QgsCptCityArchive.findFileName) QgsCptCityArchive.copyingInfo = staticmethod(QgsCptCityArchive.copyingInfo) diff --git a/python/core/auto_generated/symbology/qgscptcityarchive.sip.in b/python/core/auto_generated/symbology/qgscptcityarchive.sip.in index f39177086c7..6efdb154ef3 100644 --- a/python/core/auto_generated/symbology/qgscptcityarchive.sip.in +++ b/python/core/auto_generated/symbology/qgscptcityarchive.sip.in @@ -78,32 +78,85 @@ Base class for all items in the model bool hasChildren(); int rowCount(); + virtual int leafCount() const; +%Docstring +Returns the total count of "leaf" items (all children which are end nodes). +%End virtual void refresh(); virtual QVector createChildren(); +%Docstring +Returns a vector of children items. +%End virtual void populate(); +%Docstring +Populates children using children vector created by :py:func:`~QgsCptCityDataItem.createChildren`. +%End + bool isPopulated(); +%Docstring +Returns ``True`` if the item is already populated. +%End virtual void addChildItem( QgsCptCityDataItem *child /Transfer/, bool refresh = false ); +%Docstring +Inserts a new ``child`` using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals. + +The ``refresh`` argument will refresh the populated item by emitting signals to the model. +%End virtual void deleteChildItem( QgsCptCityDataItem *child ); +%Docstring +Removes and deletes a child ``item``, signals to browser are emitted. +%End virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) /TransferBack/; +%Docstring +Removes a ``child`` item but doesn't delete it, signals to browser are emitted. + +:return: pointer to the removed item or ``None`` if no such item was found +%End virtual bool equal( const QgsCptCityDataItem *other ); +%Docstring +Returns ``True`` if this item is equal to an ``other`` item. +%End - virtual QWidget *paramWidget() /Factory/; + virtual QWidget *paramWidget() /Deprecated/; +%Docstring - virtual bool acceptDrop(); +.. deprecated:: 3.40 - virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ ); + Is unused and will be removed in QGIS 4.0. +%End + + virtual bool acceptDrop() /Deprecated/; +%Docstring +Returns ``True`` if the item accepts drag & dropped layers - e.g. for import. + +.. deprecated:: 3.40 + + Is unused and will be removed in QGIS 4.0. +%End + + virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) /Deprecated/; +%Docstring +Tries to process the ``data`` dropped on this item. + +.. deprecated:: 3.40 + + Is unused and will be removed in QGIS 4.0. +%End static int findItem( QVector items, QgsCptCityDataItem *item ); +%Docstring +Finds a child index in vector of items using '==' operator. +%End Type type() const; @@ -128,10 +181,50 @@ Base class for all items in the model signals: + void beginInsertItems( QgsCptCityDataItem *parent, int first, int last ); +%Docstring +Emitted before child items are added to this item. + +This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`. + +:param parent: the parent item having children added +:param first: index of first child item to be added +:param last: index last child item, after the addition has occurred + +.. seealso:: :py:func:`endInsertItems` +%End + void endInsertItems(); +%Docstring +Emitted after child items have been added to this data item. + +This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`. + +.. seealso:: :py:func:`beginInsertItems` +%End + void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last ); +%Docstring +Emitted before child items are removed from this data item. + +This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`. + +:param parent: the parent item having children removed +:param first: index of first child item to be removed +:param last: index of the last child item to be removed + +.. seealso:: :py:func:`endRemoveItems` +%End + void endRemoveItems(); +%Docstring +Emitted after child items have been removed from this data item. + +This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`. + +.. seealso:: :py:func:`beginRemoveItems` +%End }; class QgsCptCityColorRampItem : QgsCptCityDataItem @@ -331,8 +424,6 @@ Returns index of a path virtual void fetchMore( const QModelIndex &parent ); - signals: - public slots: void beginInsertItems( QgsCptCityDataItem *parent, int first, int last ); diff --git a/src/core/symbology/qgscptcityarchive.h b/src/core/symbology/qgscptcityarchive.h index 330c22d7936..6ae0b460b11 100644 --- a/src/core/symbology/qgscptcityarchive.h +++ b/src/core/symbology/qgscptcityarchive.h @@ -114,44 +114,79 @@ class CORE_EXPORT QgsCptCityDataItem : public QObject bool hasChildren(); int rowCount(); - // retrieve total count of "leaf" items (all children which are end nodes) + + /** + * Returns the total count of "leaf" items (all children which are end nodes). + */ virtual int leafCount() const; // virtual void refresh(); - // Create vector of children + /** + * Returns a vector of children items. + */ virtual QVector createChildren(); - // Populate children using children vector created by createChildren() + /** + * Populates children using children vector created by createChildren(). + */ virtual void populate(); + + /** + * Returns TRUE if the item is already populated. + */ bool isPopulated() { return mPopulated; } - // Insert new child using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals - // refresh - refresh populated item, emit signals to model + /** + * Inserts a new \a child using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals. + * + * The \a refresh argument will refresh the populated item by emitting signals to the model. + */ virtual void addChildItem( QgsCptCityDataItem *child SIP_TRANSFER, bool refresh = false ); - // remove and delete child item, signals to browser are emitted + /** + * Removes and deletes a child \a item, signals to browser are emitted. + */ virtual void deleteChildItem( QgsCptCityDataItem *child ); - // remove child item but don't delete it, signals to browser are emitted - // returns pointer to the removed item or null if no such item was found + /** + * Removes a \a child item but doesn't delete it, signals to browser are emitted. + * + * \returns pointer to the removed item or NULLPTR if no such item was found + */ virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) SIP_TRANSFERBACK; + /** + * Returns TRUE if this item is equal to an \a other item. + */ virtual bool equal( const QgsCptCityDataItem *other ); - virtual QWidget *paramWidget() SIP_FACTORY { return nullptr; } + /** + * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0. + */ + Q_DECL_DEPRECATED virtual QWidget *paramWidget() SIP_DEPRECATED { return nullptr; } - // whether accepts drag&drop'd layers - e.g. for import - virtual bool acceptDrop() { return false; } + /** + * Returns TRUE if the item accepts drag & dropped layers - e.g. for import. + * + * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0. + */ + Q_DECL_DEPRECATED virtual bool acceptDrop() SIP_DEPRECATED { return false; } - // try to process the data dropped on this item - virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ ) { return false; } + /** + * Tries to process the \a data dropped on this item. + * + * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0. + */ + Q_DECL_DEPRECATED virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) SIP_DEPRECATED { Q_UNUSED( data ); Q_UNUSED( action ); return false; } // static methods - // Find child index in vector of items using '==' operator + /** + * Finds a child index in vector of items using '==' operator. + */ static int findItem( QVector items, QgsCptCityDataItem *item ); // members @@ -189,9 +224,49 @@ class CORE_EXPORT QgsCptCityDataItem : public QObject bool mValid; signals: + + /** + * Emitted before child items are added to this item. + * + * This signal *must* be followed by endInsertItems(). + * + * \param parent the parent item having children added + * \param first index of first child item to be added + * \param last index last child item, after the addition has occurred + * + * \see endInsertItems() + */ void beginInsertItems( QgsCptCityDataItem *parent, int first, int last ); + + /** + * Emitted after child items have been added to this data item. + * + * This signal will always be preceded by beginInsertItems(). + * + * \see beginInsertItems() + */ void endInsertItems(); + + /** + * Emitted before child items are removed from this data item. + * + * This signal *must* be followed by endRemoveItems(). + * + * \param parent the parent item having children removed + * \param first index of first child item to be removed + * \param last index of the last child item to be removed + * + * \see endRemoveItems() + */ void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last ); + + /** + * Emitted after child items have been removed from this data item. + * + * This signal will always be preceded by beginRemoveItems(). + * + * \see beginRemoveItems() + */ void endRemoveItems(); }; @@ -379,8 +454,6 @@ class CORE_EXPORT QgsCptCityBrowserModel : public QAbstractItemModel bool canFetchMore( const QModelIndex &parent ) const override; void fetchMore( const QModelIndex &parent ) override; - signals: - public slots: //void removeItems( QgsCptCityDataItem * parent, QVectoritems ); //void addItems( QgsCptCityDataItem * parent, QVectoritems );