documentation, licence header and renaming

qgis · Sep 11, 2020 · d2f422d · d2f422d
1 parent 54660aa
commit d2f422d
Show file tree

Hide file tree

Showing 4 changed files with 125 additions and 37 deletions.
diff --git a/src/quickgui/plugin/editor/qgsquickvaluerelation.qml b/src/quickgui/plugin/editor/qgsquickvaluerelation.qml
@@ -57,13 +57,13 @@ Item {
 
       // recalculate index when model changes
       onModelReset: {
-        combobox.currentIndex = vrModel.rowIndexFromKeyModel( value )
+        combobox.currentIndex = vrModel.rowModelIndexFromKey( value )
       }
     }
 
     Component.onCompleted: {
         vrModel.populate(config)
-        currentIndex = vrModel.rowIndexFromKeyModel( value )
+        currentIndex = vrModel.rowModelIndexFromKey( value )
     }
 
     onPressedChanged: {
@@ -76,13 +76,13 @@ Item {
 
     // Called when user makes selection in the combo box
     onItemClicked: {
-        currentIndex = vrModel.rowIndexFromKeyModel( index )
+        currentIndex = vrModel.rowModelIndexFromKey( index )
         valueChanged( index, false )
     }
 
     // Called when the same form is used for a different feature
     onCurrentEditorValueChanged: {
-        currentIndex = vrModel.rowIndexFromKeyModel( value );
+        currentIndex = vrModel.rowModelIndexFromKey( value );
     }
   }
 }
diff --git a/src/quickgui/plugin/qgsquickfeatureform.qml b/src/quickgui/plugin/qgsquickfeatureform.qml
@@ -36,16 +36,6 @@ Item {
    */
   signal canceled
 
-  /**
-    */
-  property var customWidgetCallback: QtObject {
-
-    property var valueRelationOpened: function valueRelationOpened( widget, valueRelationModel ) {
-      // by default just open combobox
-      widget.openCombobox()
-    }
-  }
-
    /**
     * A handler for extra events in externalSourceWidget.
     */
@@ -92,6 +82,21 @@ Item {
         }
     }
 
+  /**
+   * Support for custom callback on events happening in widgets
+   */
+  property var customWidgetCallback: QtObject {
+
+    /**
+     * Called when user clicks on valuerelation widget and combobox shall open
+     * \param widget valuerelation widget for specific field to send valueChanged signal.
+     * \param valueRelationModel model of type FeaturesListModel bears features of related layer.
+     */
+    property var valueRelationOpened: function valueRelationOpened( widget, valueRelationModel ) {
+      widget.openCombobox() // by default just open combobox
+    }
+  }
+
   /**
    * AttributeFormModel binded on a feature supporting auto-generated editor layouts and "tab" layout.
    */

diff --git a/src/quickgui/qgsquickfeatureslistmodel.cpp b/src/quickgui/qgsquickfeatureslistmodel.cpp
@@ -1,7 +1,21 @@
+/***************************************************************************
+  qgsquickfeatureslistmodel.cpp
+ ---------------------------
+  Date                 : Sep 2020
+  Copyright            : (C) 2020 by Tomas Mizera
+  Email                : tomas.mizera2 at gmail dot com
+ ***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
 #include "qgsquickfeatureslistmodel.h"
 #include "qgsexpressioncontextutils.h"
 #include "qgslogger.h"
-#include "qvariant.h"
 
 QgsQuickFeaturesListModel::QgsQuickFeaturesListModel( QObject *parent )
   : QAbstractListModel( parent ),
@@ -177,6 +191,11 @@ void QgsQuickFeaturesListModel::populateFromLayer( QgsVectorLayer *layer )
   endResetModel();
 }
 
+void QgsQuickFeaturesListModel::reloadFeatures()
+{
+  loadFeaturesFromLayer();
+}
+
 void QgsQuickFeaturesListModel::emptyData()
 {
   mFeatures.clear();
@@ -240,17 +259,17 @@ int QgsQuickFeaturesListModel::rowIndexFromKey( const QVariant &key ) const
     if ( mCache[i].key == key )
       return i;
   }
-  QgsDebugMsg( "rowForKey: key not found: " + key.toString() );
+  QgsDebugMsg( "rowIndexFromKey: key not found: " + key.toString() );
   return -1;
 }
 
-int QgsQuickFeaturesListModel::rowIndexFromKeyModel( const QVariant &key ) const
+int QgsQuickFeaturesListModel::rowModelIndexFromKey( const QVariant &key ) const
 {
   for ( int i = 0; i < mFeatures.count(); ++i )
   {
     if ( mFeatures[i].feature().attribute( mKeyFieldName ) == key )
       return i;
   }
-  QgsDebugMsg( "Could not find index in features model, index: " + key.toString() );
+  QgsDebugMsg( "rowModelIndexFromKey: Could not find index in features model, index: " + key.toString() );
   return -1;
 }
diff --git a/src/quickgui/qgsquickfeatureslistmodel.h b/src/quickgui/qgsquickfeatureslistmodel.h
@@ -1,3 +1,18 @@
+/***************************************************************************
+  qgsquickfeatureslistmodel.h
+ ---------------------------
+  Date                 : Sep 2020
+  Copyright            : (C) 2020 by Tomas Mizera
+  Email                : tomas.mizera2 at gmail dot com
+ ***************************************************************************
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
 #ifndef QGSQUICKFEATURESMODEL_H
 #define QGSQUICKFEATURESMODEL_H
 
@@ -7,23 +22,57 @@
 #include "qgsquickfeaturelayerpair.h"
 #include "qgsvaluerelationfieldformatter.h"
 
+/**
+ * \ingroup quick
+ * List Model holding features of specific layer.
+ *
+ * Model allows searching by any string or number attribute.
+ *
+ * Note that the model can run in several modes:
+ *  (1) as a features list - usable in listing features from specifig layer
+ *  (2) as a value relation model - filling value-relation widget with data from config
+ *
+ * \note QML Type: FeaturesListModel
+ *
+ * \since QGIS 3.14
+ */
 class QUICK_EXPORT QgsQuickFeaturesListModel : public QAbstractListModel
 {
     Q_OBJECT
 
+    /**
+     * Read only property holding true number of features in layer - not only requested features
+     * Changing filter expression does not result in changing this number
+     */
     Q_PROPERTY( int featuresCount READ featuresCount NOTIFY featuresCountChanged )
+
+    /**
+     * Filter Expression represents filter used when querying for data in current layer.
+     * String and numerical attributes are compared with filterExpression
+     */
     Q_PROPERTY( QString filterExpression READ filterExpression WRITE setFilterExpression NOTIFY filterExpressionChanged )
+
+    /**
+     * Property limiting maximum number of features queried from layer
+     * Read only property
+     */
     Q_PROPERTY( int featuresLimit READ featuresLimit NOTIFY featuresLimitChanged )
+
+    /**
+     * Property determining behaviour of Feature Model.
+     *
+     * \note ValueRelation type provides different attribute when opting for data with EmitableIndex role, it returns "key" attribute
+     */
     Q_PROPERTY( modelTypes modelType READ modelType WRITE setModelType )
 
     enum roleNames
     {
       FeatureTitle = Qt::UserRole + 1,
       FeatureId,
       Feature,
-      Description, // secondary text in list view
-      EmitableIndex, // key in value relation
-      FoundPair // pair of attribute and its value by which the feature was found, empty if mFilterExpression is empty
+      Description, //! secondary text in list view
+      EmitableIndex, //! key in value relation
+      FoundPair //! pair of attribute and its value by which the feature was found, empty if mFilterExpression is empty
     };
 
   public:
@@ -35,6 +84,7 @@ class QUICK_EXPORT QgsQuickFeaturesListModel : public QAbstractListModel
     };
     Q_ENUM( modelTypes );
 
+    //! Create features list model
     explicit QgsQuickFeaturesListModel( QObject *parent = nullptr );
     ~QgsQuickFeaturesListModel() override {};
 
@@ -45,26 +95,32 @@ class QUICK_EXPORT QgsQuickFeaturesListModel : public QAbstractListModel
     QVariant data( const QModelIndex &index, int role = Qt::DisplayRole ) const override;
     QHash<int, QByteArray> roleNames() const override;
 
-    //! Features count represents real number of features in layer being browsed
-    int featuresCount() const;
-
-    QString filterExpression() const;
-    void setFilterExpression( const QString &filterExpression );
-
-    int featuresLimit() const;
-
+    /**
+     * @brief populate populates model with value relation data from config
+     * @param config to be used
+     */
     Q_INVOKABLE void populate( const QVariantMap &config );
 
+    /**
+     * @brief populateFromLayer populates model with features from layer
+     * @param layer to be used
+     */
     Q_INVOKABLE void populateFromLayer( QgsVectorLayer *layer );
 
-    Q_INVOKABLE void loadFeaturesFromLayer( QgsVectorLayer *layer = nullptr );
+    /**
+     * @brief reloadFeatures reloads features from current layer
+     */
+    Q_INVOKABLE void reloadFeatures();
 
-    //! Returns row number
+    //! Methods to translate value relation key into model index
     Q_INVOKABLE int rowIndexFromKey( const QVariant &key ) const;
+    Q_INVOKABLE int rowModelIndexFromKey( const QVariant &key ) const;
 
-    Q_INVOKABLE int rowIndexFromKeyModel( const QVariant &key ) const;
-
+    int featuresLimit() const;
+    int featuresCount() const;
     modelTypes modelType() const;
+    QString filterExpression() const;
+    void setFilterExpression( const QString &filterExpression );
 
   public slots:
     void setModelType( modelTypes modelType );
@@ -75,7 +131,14 @@ class QUICK_EXPORT QgsQuickFeaturesListModel : public QAbstractListModel
     void filterExpressionChanged( QString filterExpression );
 
   private:
-    //! Empty data when changing map theme or project
+
+    /**
+     * @brief loadFeaturesFromLayer
+     * @param layer
+     */
+    void loadFeaturesFromLayer( QgsVectorLayer *layer = nullptr );
+
+    //! Empty data when resetting model
     void emptyData();
 
     //! Builds feature title in list
@@ -97,18 +160,19 @@ class QUICK_EXPORT QgsQuickFeaturesListModel : public QAbstractListModel
     //! Number of maximum features loaded from layer
     const int FEATURES_LIMIT = 10000;
 
-    //! Search string, change of string results in reloading features from layer with this text
+    //! Search string, change of string results in reloading features from mCurrentLayer
     QString mFilterExpression;
 
-    //! Pointer to layer that is currently parsed
+    //! Pointer to layer that is currently loaded
     QgsVectorLayer *mCurrentLayer = nullptr;
 
     //! Data from config for value relations
     QgsValueRelationFieldFormatter::ValueRelationCache mCache;
 
-    //! Type of a model - Listing (browsing) features or use in Value relation widget
+    //! Type of a model - Listing (browsing) features or use in value relation widget
     modelTypes mModelType;
 
+    //! Field that is used as a "key" in value relation
     QString mKeyFieldName;
 };