Allow empty field name ('not set' option) in QgsFieldModel, QgsFieldComboBox

Author: nyalldawson

python/gui/qgsfieldcombobox.sip

@@ -25,6 +25,20 @@ class QgsFieldComboBox : QComboBox
     //! currently used filter on list of fields
     QgsFieldProxyModel::Filters filters() const;
 
+    /**
+     * Sets whether an optional empty field ("not set") option is shown in the combo box.
+     * @see allowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    void setAllowEmptyFieldName( bool allowEmpty );
+
+    /**
+     * Returns true if the combo box allows the empty field ("not set") choice.
+     * @see setAllowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    bool allowEmptyFieldName() const;
+
     //! return the currently selected field
     QString currentField() const;
 

python/gui/qgsfieldmodel.sip

@@ -12,6 +12,8 @@ class QgsFieldModel : QAbstractItemModel
 %End
 
   public:
+
+    //! Roles utilised by the model
     enum FieldRoles
     {
       FieldNameRole, /*!< return field name if index corresponds to a field */
@@ -21,38 +23,85 @@ class QgsFieldModel : QAbstractItemModel
       ExpressionValidityRole, /*!< return if expression is valid or not */
       FieldTypeRole, /*!< return the field type (if a field, return QVariant if expression) */
       FieldOriginRole, /*!< return the field origin (if a field, returns QVariant if expression) */
+      IsEmptyRole, //!< Return if the index corresponds to the empty value
     };
 
     /**
-     * @brief QgsFieldModel creates a model to display the fields of a given layer
+     * Constructor for QgsFieldModel - creates a model to display the fields of a given layer.
      */
     explicit QgsFieldModel( QObject *parent /TransferThis/ = 0 );
 
-    //! return the index corresponding to a given fieldName
+    /**
+     * Returns the index corresponding to a given fieldName.
+     */
     QModelIndex indexFromName( const QString &fieldName );
 
-    //! returns the currently used layer
+    /**
+     * Sets whether custom expressions are accepted and displayed in the model.
+     * @see allowExpression()
+     * @see setExpression()
+     */
     void setAllowExpression( bool allowExpression );
+
+    /**
+     * Returns true if the model allows custom expressions to be created and displayed.
+     * @see setAllowExpression()
+     */
     bool allowExpression();
 
-    bool isField( const QString& expression );
+    /**
+     * Sets whether an optional empty field ("not set") option is present in the model.
+     * @see allowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    void setAllowEmptyFieldName( bool allowEmpty );
+
+    /**
+     * Returns true if the model allows the empty field ("not set") choice.
+     * @see setAllowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    bool allowEmptyFieldName() const;
 
     /**
-     * @brief setExpression sets a single expression to be added after the fields at the end of the model
+     * Returns true if a string represents a field reference, or false if it is an
+     * expression consisting of more than direct field reference.
+     */
+    bool isField( const QString& expression ) const;
+
+    /**
+     * Sets a single expression to be added after the fields at the end of the model.
+     * @see setAllowExpression()
+     * @see allowExpression()
+     * @see removeExpression()
      */
     void setExpression( const QString &expression );
 
-    //! remove expressions from the model
+    /**
+     * Removes any custom expression from the model.
+     * @see setExpression()
+     * @see allowExpression()
+     */
     void removeExpression();
 
-    //! returns the currently used layer
+    /**
+     * Returns the layer associated with the model.
+     * @see setLayer()
+     */
     QgsVectorLayer* layer();
 
   public slots:
-    //! set the layer of whch fields are displayed
+    /**
+     * Set the layer from which fields are displayed.
+     * @see layer()
+     */
     void setLayer( QgsVectorLayer *layer );
 
   protected slots:
+
+    /**
+     * Called when the model must be updated.
+     */
     virtual void updateModel();
 
     // QAbstractItemModel interface

src/gui/qgsfieldcombobox.cpp

@@ -33,6 +33,16 @@ void QgsFieldComboBox::setFilters( QgsFieldProxyModel::Filters filters )
   mFieldProxyModel->setFilters( filters );
 }
 
+void QgsFieldComboBox::setAllowEmptyFieldName( bool allowEmpty )
+{
+  mFieldProxyModel->sourceFieldModel()->setAllowEmptyFieldName( allowEmpty );
+}
+
+bool QgsFieldComboBox::allowEmptyFieldName() const
+{
+  return mFieldProxyModel->sourceFieldModel()->allowEmptyFieldName();
+}
+
 void QgsFieldComboBox::setLayer( QgsMapLayer *layer )
 {
   QgsVectorLayer* vl = dynamic_cast<QgsVectorLayer*>( layer );

src/gui/qgsfieldcombobox.h

@@ -35,6 +35,7 @@ class GUI_EXPORT QgsFieldComboBox : public QComboBox
     Q_OBJECT
     Q_FLAGS( QgsFieldProxyModel::Filters )
     Q_PROPERTY( QgsFieldProxyModel::Filters filters READ filters WRITE setFilters )
+    Q_PROPERTY( bool allowEmptyFieldName READ allowEmptyFieldName WRITE setAllowEmptyFieldName )
 
   public:
 
@@ -50,6 +51,20 @@ class GUI_EXPORT QgsFieldComboBox : public QComboBox
     //! currently used filter on list of fields
     QgsFieldProxyModel::Filters filters() const { return mFieldProxyModel->filters(); }
 
+    /**
+     * Sets whether an optional empty field ("not set") option is shown in the combo box.
+     * @see allowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    void setAllowEmptyFieldName( bool allowEmpty );
+
+    /**
+     * Returns true if the combo box allows the empty field ("not set") choice.
+     * @see setAllowEmptyFieldName()
+     * @note added in QGIS 3.0
+     */
+    bool allowEmptyFieldName() const;
+
     //! return the currently selected field
     QString currentField() const;