Add QgsOptional and QgsOptionalExpression

python/core/core.sip

@@ -105,6 +105,7 @@
 %Include qgsobjectcustomproperties.sip
 %Include qgsofflineediting.sip
 %Include qgsogcutils.sip
+%Include qgsoptionalexpression.sip
 %Include qgsowsconnection.sip
 %Include qgspaintenginehack.sip
 %Include qgspainting.sip

python/core/qgsexpression.sip

@@ -12,6 +12,13 @@ class QgsExpression
      * loop in which this expression is used.
      */
     QgsExpression( const QString& expr );
+    /**
+     * Create an empty expression.
+     *
+     * @note Added in QGIS 3.0
+     */
+    QgsExpression();
+
     ~QgsExpression();
 
     /**
@@ -85,6 +92,13 @@ class QgsExpression
      */
     static bool checkExpression( const QString& text, const QgsExpressionContext* context, QString &errorMessage );
 
+    /**
+     * Set the expression string, will reset the whole internal structure.
+     *
+     * @note Added in QGIS 3.0
+     */
+    void setExpression( const QString& expression );
+
     //! Return the original, unmodified expression string.
     //! If there was none supplied because it was constructed by sole
     //! API calls, dump() will be used to create one instead.

python/core/qgsoptionalexpression.sip

@@ -0,0 +1,83 @@
+/***************************************************************************
+  qgsoptionalexpression.sip - QgsOptionalExpression
+
+ ---------------------
+ begin                : 8.9.2016
+ copyright            : (C) 2016 by Matthias Kuhn
+ email                : matthias@opengis.ch
+ ***************************************************************************
+ *                                                                         *
+ *   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.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
+/**
+ * \ingroup core
+ *
+ * QgsOptionalExpression is a container for an expression with an additional enabled/disabled flag.
+ *
+ * @note Added in QGIS 3.0
+ */
+class QgsOptionalExpression
+{
+%TypeHeaderCode
+#include <qgsoptionalexpression.h>
+%End
+  public:
+    /**
+     * A QgsOptionalExpression is disabled by default if default constructed.
+     */
+    QgsOptionalExpression();
+
+    /**
+     * A QgsOptionalExpression is enabled by default if constructed with an expression.
+     */
+    QgsOptionalExpression( const QgsExpression& data );
+
+    /**
+     * A QgsOptionalExptression constructed with enabled status and data
+     */
+    QgsOptionalExpression( const QgsExpression& data, bool enabled );
+
+    /**
+     * Compare this QgsOptionalExptression to another one.
+     *
+     * This will compare the enabled flag and call the == operator
+     * of the contained class.
+     *
+     * @note Added in QGIS 3.0
+     */
+    bool operator== ( const QgsOptionalExpression& other ) const;
+    operator bool () const;
+
+    /**
+     * Check if this optional is enabled
+     *
+     * @note Added in QGIS 3.0
+     */
+    bool enabled() const;
+
+    /**
+     * Set if this optional is enabled
+     *
+     * @note Added in QGIS 3.0
+     */
+    void setEnabled( bool enabled );
+
+    /**
+     * Access the payload data
+     *
+     * @note Added in QGIS 3.0
+     */
+    QgsExpression data() const;
+
+    /**
+     * Set the payload data
+     *
+     * @note Added in QGIS 3.0
+     */
+    void setData( const QgsExpression& data );
+};

src/core/CMakeLists.txt

@@ -164,6 +164,7 @@ SET(QGIS_CORE_SRCS
   qgsofflineediting.cpp
   qgsogcutils.cpp
   qgsogrutils.cpp
+  qgsoptional.cpp
   qgsowsconnection.cpp
   qgspaintenginehack.cpp
   qgspainting.cpp
@@ -672,6 +673,8 @@ SET(QGIS_CORE_HDRS
   qgsmultirenderchecker.h
   qgsobjectcustomproperties.h
   qgsogcutils.h
+  qgsoptional.h
+  qgsoptionalexpression.h
   qgsowsconnection.h
   qgspaintenginehack.h
   qgspainting.h

src/core/qgsexpression.h

@@ -123,6 +123,7 @@ class CORE_EXPORT QgsExpression
      * it does not need to be re-parsed.
      */
     QgsExpression( const QgsExpression& other );
+
     /**
      * Create a copy of this expression. This is preferred
      * over recreating an expression from a string since
@@ -131,7 +132,9 @@ class CORE_EXPORT QgsExpression
     QgsExpression& operator=( const QgsExpression& other );
 
     /**
-     * Create an empty expression
+     * Create an empty expression.
+     *
+     * @note Added in QGIS 3.0
      */
     QgsExpression();
 
@@ -171,7 +174,8 @@ class CORE_EXPORT QgsExpression
 
     /**
      * Get list of columns referenced by the expression.
-     * @note if the returned list contains the QgsFeatureRequest::AllAttributes constant then
+     *
+     * @note If the returned list contains the QgsFeatureRequest::AllAttributes constant then
      * all attributes from the layer are required for evaluation of the expression.
      * QgsFeatureRequest::setSubsetOfAttributes automatically handles this case.
      *

src/core/qgsoptional.cpp

@@ -0,0 +1,16 @@
+/***************************************************************************
+  qgsoptional.cpp - QgsOptional
+
+ ---------------------
+ begin                : 7.9.2016
+ copyright            : (C) 2016 by Matthias Kuhn
+ email                : matthias@opengis.ch
+ ***************************************************************************
+ *                                                                         *
+ *   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 "qgsoptional.h"

src/core/qgsoptional.h

@@ -0,0 +1,137 @@
+/***************************************************************************
+  qgsoptional.h - QgsOptional
+
+ ---------------------
+ begin                : 7.9.2016
+ copyright            : (C) 2016 by Matthias Kuhn
+ email                : matthias@opengis.ch
+ ***************************************************************************
+ *                                                                         *
+ *   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 QGSOPTIONAL_H
+#define QGSOPTIONAL_H
+
+/**
+ * \ingroup core
+ *
+ * \brief
+ * QgsOptional is a container for other classes and adds an additional enabled/disabled flag.
+ *
+ * Often it is used for configuration options which can be enabled or disabled but also have
+ * more internal configuration information that should not be lost when disabling and re-enabling.
+ *
+ * @note Added in QGIS 3.0
+ * @note For python you need to use implementations for specific template classes
+ */
+template<class T>
+class CORE_EXPORT QgsOptional
+{
+  public:
+    /**
+     * A QgsOptional is disabled by default if default constructed.
+     */
+    QgsOptional()
+        : mEnabled( false )
+    {
+    }
+
+    /**
+     * A QgsOptional is enabled by default if constructed with payload.
+     */
+    QgsOptional( const T& data )
+        : mEnabled( true )
+        , mData( data )
+    {
+    }
+
+    /**
+     * A QgsOptional constructed with enabled status and data
+     */
+    QgsOptional( const T& data, bool enabled )
+        : mEnabled( enabled )
+        , mData( data )
+    {
+    }
+
+    /**
+     * Compare this QgsOptional to another one.
+     *
+     * This will compare the enabled flag and call the == operator
+     * of the contained class.
+     *
+     * @note Added in QGIS 3.0
+     */
+    bool operator== ( const QgsOptional<T>& other ) const
+    {
+      return mEnabled == other.mEnabled && mData == other.mData;
+    }
+
+    /**
+     * Boolean operator. Will return true if this optional is enabled.
+     */
+    operator bool() const
+    {
+      return mEnabled;
+    }
+
+    /**
+     * Check if this optional is enabled
+     *
+     * @note Added in QGIS 3.0
+     */
+    bool enabled() const
+    {
+      return mEnabled;
+    }
+
+    /**
+     * Set if this optional is enabled
+     *
+     * @note Added in QGIS 3.0
+     */
+    void setEnabled( bool enabled )
+    {
+      mEnabled = enabled;
+    }
+
+    /**
+     * Access the payload data
+     *
+     * @note Added in QGIS 3.0
+     */
+    const T* operator->() const
+    {
+      return &mData;
+    }
+
+    /**
+     * Access the payload data
+     *
+     * @note Added in QGIS 3.0
+     */
+    T data() const
+    {
+      return mData;
+    }
+
+    /**
+     * Set the payload data
+     *
+     * @note Added in QGIS 3.0
+     */
+    void setData( const T& data )
+    {
+      mData = data;
+    }
+
+  private:
+    T mData;
+    bool mEnabled;
+};
+
+#endif // QGSOPTIONAL_H

src/core/qgsoptionalexpression.h

@@ -0,0 +1,33 @@
+/***************************************************************************
+  qgsoptionalexpression - %{Cpp:License:ClassName}
+
+ ---------------------
+ begin                : 8.9.2016
+ copyright            : (C) 2016 by Matthias Kuhn
+ email                : matthias@opengis.ch
+ ***************************************************************************
+ *                                                                         *
+ *   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 QGSOPTIONALEXPRESSION_H
+#define QGSOPTIONALEXPRESSION_H
+
+#include "qgsoptional.h"
+#include "qgsexpression.h"
+
+/**
+ * An expression with an additional enabled flag.
+ *
+ * This can be used for configuration options where an expression can be enabled
+ * or diabled but when disabled it shouldn't lose it's information for the case
+ * it gets re-enabled later on and a user shoulnd't be force to redo the configuration.
+ *
+ * Added in QGIS 3.0
+ */
+typedef QgsOptional<QgsExpression> QgsOptionalExpression;
+
+#endif // QGSOPTIONALEXPRESSION_H

tests/src/python/CMakeLists.txt

@@ -62,6 +62,7 @@ ADD_PYTHON_TEST(PyQgsNullSymbolRenderer test_qgsnullsymbolrenderer.py)
 ADD_PYTHON_TEST(PyQgsNewGeoPackageLayerDialog test_qgsnewgeopackagelayerdialog.py)
 ADD_PYTHON_TEST(PyQgsOGRProviderGpkg test_provider_ogr_gpkg.py)
 ADD_PYTHON_TEST(PyQgsOGRProviderSqlite test_provider_ogr_sqlite.py)
+ADD_PYTHON_TEST(PyQgsOptional test_qgsoptional.py)
 ADD_PYTHON_TEST(PyQgsPalLabelingBase test_qgspallabeling_base.py)
 ADD_PYTHON_TEST(PyQgsPalLabelingCanvas test_qgspallabeling_canvas.py)
 ADD_PYTHON_TEST(PyQgsPalLabelingComposer test_qgspallabeling_composer.py)

tests/src/python/test_qgsoptional.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+'''
+test_qgsoptional.py
+                     --------------------------------------
+               Date                 : September 2016
+               Copyright            : (C) 2016 Matthias Kuhn
+               email                : matthias@opengis.ch
+ ***************************************************************************
+ *                                                                         *
+ *   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.                                   *
+ *                                                                         *
+ ***************************************************************************/
+'''
+
+import qgis  # NOQA
+
+from qgis.testing import unittest
+from qgis.core import QgsOptionalExpression, QgsExpression
+
+
+class TestQgsOptional(unittest.TestCase):
+
+    def setUp(self):
+        """Run before each test."""
+        pass
+
+    def tearDown(self):
+        """Run after each test."""
+        pass
+
+    def testQgsOptionalExpression(self):
+        opt = QgsOptionalExpression()
+        self.assertFalse(opt.enabled())
+
+        opt = QgsOptionalExpression(QgsExpression('true'))
+        self.assertTrue(opt.enabled())
+        self.assertEquals(opt.data().expression(), 'true')
+        opt.setEnabled(False)
+        self.assertFalse(opt.enabled())
+        # boolean operator not yet working in python
+        # self.assertFalse(opt)
+        self.assertEquals(opt.data().expression(), 'true')
+        opt.setEnabled(True)
+        self.assertTrue(opt.enabled())
+        # self.assertTrue(opt)
+        self.assertEquals(opt.data().expression(), 'true')
+        opt.setData(QgsExpression('xyz'))
+        self.assertTrue(opt.enabled())
+        self.assertEquals(opt.data().expression(), 'xyz')
+
+        opt = QgsOptionalExpression(QgsExpression('true'), False)
+        self.assertFalse(opt.enabled())
+
+
+if __name__ == '__main__':
+    unittest.main()