Merge pull request #3468 from nyalldawson/spin_box_v2

Rework Qgs(Double)SpinBox clear handling

Author: nyalldawson

python/gui/editorwidgets/qgsdoublespinbox.sip

@@ -1,22 +1,40 @@
+/** \ingroup gui
+ * @brief The QgsSpinBox is a spin box with a clear button that will set the value to the defined clear value.
+ * The clear value can be either the minimum or the maiximum value of the spin box or a custom value.
+ * This value can then be handled by a special value text.
+ */
+
 class QgsDoubleSpinBox : QDoubleSpinBox
 {
 %TypeHeaderCode
 #include <qgsdoublespinbox.h>
 %End
 
   public:
+
+    //! Behaviour when widget is cleared.
     enum ClearValueMode
     {
-      MinimumValue,
-      MaximumValue,
-      CustomValue
+      MinimumValue, //!< Reset value to minimum()
+      MaximumValue, //!< Reset value to maximum()
+      CustomValue, //!< Reset value to custom value (see setClearValue() )
     };
 
+    /** Constructor for QgsDoubleSpinBox.
+     * @param parent parent widget
+     */
     explicit QgsDoubleSpinBox( QWidget *parent /TransferThis/ = 0 );
 
-    //! determines if the widget will show a clear button
-    //! @note the clear button will set the widget to its minimum value
+    /** Sets whether the widget will show a clear button. The clear button
+     * allows users to reset the widget to a default or empty state.
+     * @param showClearButton set to true to show the clear button, or false to hide it
+     * @see showClearButton()
+     */
     void setShowClearButton( const bool showClearButton );
+
+    /** Returns whether the widget is showing a clear button.
+     * @see setShowClearButton()
+     */
     bool showClearButton() const;
 
     /** Sets if the widget will allow entry of simple expressions, which are
@@ -25,6 +43,7 @@ class QgsDoubleSpinBox : QDoubleSpinBox
      * @note added in QGIS 2.7
      */
     void setExpressionsEnabled( const bool enabled );
+
     /** Returns whether the widget will allow entry of simple expressions, which are
      * evaluated and then discarded.
      * @returns true if spin box allows expression entry
@@ -36,26 +55,29 @@ class QgsDoubleSpinBox : QDoubleSpinBox
     virtual void clear();
 
     /**
-     * @brief setClearValue defines the clear value as a custom value and will automatically set the clear value mode to CustomValue
+     * Defines the clear value as a custom value and will automatically set the clear value mode to CustomValue.
      * @param customValue defines the numerical value used as the clear value
      * @param clearValueText is the text displayed when the spin box is at the clear value. If not specified, no special value text is used.
+     * @see setClearValue()
      */
     void setClearValue( double customValue, const QString& clearValueText = QString() );
+
     /**
-     * @brief setClearValueMode defines if the clear value should be the minimum or maximum values of the widget or a custom value
+     * Defines if the clear value should be the minimum or maximum values of the widget or a custom value.
      * @param mode mode to user for clear value
      * @param clearValueText is the text displayed when the spin box is at the clear value. If not specified, no special value text is used.
      */
     void setClearValueMode( ClearValueMode mode, const QString& clearValueText = QString() );
 
-    //! returns the value used when clear() is called.
+    /** Returns the value used when clear() is called.
+     * @see setClearValue()
+     */
     double clearValue() const;
 
     virtual double valueFromText( const QString & text ) const;
     virtual QValidator::State validate( QString & input, int & pos ) const;
 
   protected:
-    virtual void resizeEvent( QResizeEvent* event );
     virtual void changeEvent( QEvent* event );
     virtual void paintEvent( QPaintEvent* event );
 };

python/gui/editorwidgets/qgsspinbox.sip

@@ -1,22 +1,40 @@
+/** \ingroup gui
+ * @brief The QgsSpinBox is a spin box with a clear button that will set the value to the defined clear value.
+ * The clear value can be either the minimum or the maiximum value of the spin box or a custom value.
+ * This value can then be handled by a special value text.
+ */
+
 class QgsSpinBox : QSpinBox
 {
 %TypeHeaderCode
 #include <qgsspinbox.h>
 %End
 
   public:
+
+    //! Behaviour when widget is cleared.
     enum ClearValueMode
     {
-      MinimumValue,
-      MaximumValue,
-      CustomValue
+      MinimumValue, //!< Reset value to minimum()
+      MaximumValue, //!< Reset value to maximum()
+      CustomValue, //!< Reset value to custom value (see setClearValue() )
     };
 
+    /** Constructor for QgsSpinBox.
+     * @param parent parent widget
+     */
     explicit QgsSpinBox( QWidget *parent /TransferThis/ = 0 );
 
-    //! determines if the widget will show a clear button
-    //! @note the clear button will set the widget to its minimum value
+    /** Sets whether the widget will show a clear button. The clear button
+     * allows users to reset the widget to a default or empty state.
+     * @param showClearButton set to true to show the clear button, or false to hide it
+     * @see showClearButton()
+     */
     void setShowClearButton( const bool showClearButton );
+
+    /** Returns whether the widget is showing a clear button.
+     * @see setShowClearButton()
+     */
     bool showClearButton() const;
 
     /** Sets if the widget will allow entry of simple expressions, which are
@@ -25,6 +43,7 @@ class QgsSpinBox : QSpinBox
      * @note added in QGIS 2.7
      */
     void setExpressionsEnabled( const bool enabled );
+
     /** Returns whether the widget will allow entry of simple expressions, which are
      * evaluated and then discarded.
      * @returns true if spin box allows expression entry
@@ -36,26 +55,30 @@ class QgsSpinBox : QSpinBox
     virtual void clear();
 
     /**
-     * @brief setClearValue defines the clear value for the widget and will automatically set the clear value mode to CustomValue
+     * Defines the clear value as a custom value and will automatically set the clear value mode to CustomValue.
      * @param customValue defines the numerical value used as the clear value
      * @param clearValueText is the text displayed when the spin box is at the clear value. If not specified, no special value text is used.
+     * @see setClearValue()
      */
     void setClearValue( int customValue, const QString& clearValueText = QString() );
+
     /**
-     * @brief setClearValueMode defines if the clear value should be the minimum or maximum values of the widget or a custom value
+     * Defines if the clear value should be the minimum or maximum values of the widget or a custom value.
      * @param mode mode to user for clear value
      * @param clearValueText is the text displayed when the spin box is at the clear value. If not specified, no special value text is used.
      */
     void setClearValueMode( ClearValueMode mode, const QString& clearValueText = QString() );
 
-    //! returns the value used when clear() is called.
+    /** Returns the value used when clear() is called.
+     * @see setClearValue()
+     */
     int clearValue() const;
 
     virtual int valueFromText( const QString & text ) const;
     virtual QValidator::State validate( QString & input, int & pos ) const;
 
   protected:
-    virtual void resizeEvent( QResizeEvent* event );
+
     virtual void changeEvent( QEvent* event );
     virtual void paintEvent( QPaintEvent* event );
 };

python/gui/qgsfilterlineedit.sip

@@ -1,46 +1,138 @@
-
-/** LineEdit with builtin clear button
- */
+/** \class QgsFilterLineEdit
+ * \ingroup gui
+ * QLineEdit subclass with built in support for clearing the widget's value and
+ * handling custom null value representations.
+ *
+ * When using QgsFilterLineEdit the value(), setValue() and clearValue() methods should be used
+ * instead of QLineEdit's text(), setText() and clear() methods, and the valueChanged()
+ * signal should be used instead of textChanged().
+ **/
 class QgsFilterLineEdit : QLineEdit
 {
 %TypeHeaderCode
 #include <qgsfilterlineedit.h>
 %End
   public:
+
+    //! Behaviour when clearing value of widget
+    enum ClearMode
+    {
+      ClearToNull, //!< Reset value to null
+      ClearToDefault, //!< Reset value to default value (see defaultValue() )
+    };
+
+    /** Constructor for QgsFilterLineEdit.
+     * @param parent parent widget
+     * @param nullValue string for representing null values
+     */
     QgsFilterLineEdit( QWidget* parent /TransferThis/ = 0, const QString& nullValue = QString::null );
 
+    /** Returns true if the widget's clear button is visible.
+     * @see setShowClearButton()
+     * @note added in QGIS 3.0
+     */
+    bool showClearButton() const;
+
+    /** Sets whether the widget's clear button is visible.
+     * @param visible set to false to hide the clear button
+     * @see showClearButton()
+     * @note added in QGIS 3.0
+     */
+    void setShowClearButton( bool visible );
+
+    /** Returns the clear mode for the widget. The clear mode defines the behaviour of the
+     * widget when its value is cleared. This defaults to ClearToNull.
+     * @see setClearMode()
+     * @note added in QGIS 3.0
+     */
+    ClearMode clearMode() const;
+
+    /** Sets the clear mode for the widget. The clear mode defines the behaviour of the
+     * widget when its value is cleared. This defaults to ClearToNull.
+     * @see clearMode()
+     * @note added in QGIS 3.0
+     */
+    void setClearMode( ClearMode mode );
+
+    /** Sets the string representation for null values in the widget. This does not
+     * affect the values returned for null values by value(), rather it only affects
+     * the text that is shown to users when the widget's value is null.
+     * @param nullValue string to show when widget's value is null
+     * @see nullValue()
+     */
     void setNullValue( const QString& nullValue );
 
+    /** Returns the string used for representating null values in the widget.
+     * @see setNullValue()
+     * @see isNull()
+     */
     QString nullValue() const;
 
+    /** Sets the default value for the widget. The default value is a value
+     * which the widget will be reset to if it is cleared and the clearMode()
+     * is equal to ClearToDefault.
+     * @param defaultValue default value
+     * @see defaultValue()
+     * @see clearMode()
+     * @note added in QGIS 3.0
+     */
+    void setDefaultValue( const QString& defaultValue );
+
+    /** Returns the default value for the widget. The default value is a value
+     * which the widget will be reset to if it is cleared and the clearMode()
+     * is equal to ClearToDefault.
+     * @see setDefaultValue()
+     * @see clearMode()
+     * @note added in QGIS 3.0
+     */
+    QString defaultValue() const;
+
     /**
-     * Sets the current text with NULL support
+     * Sets the current text for the widget with support for handling null values.
      *
-     * @param value The text to set. If a Null string is provided, the text will match the nullValue.
+     * @param value The text to set. If a null string is provided, the text shown in the
+     * widget will be set to the current nullValue().
+     * @see value()
      */
     void setValue( const QString& value );
 
     /**
-     * Returns the text of this edit with NULL support
+     * Returns the text of this edit with support for handling null values. If the text
+     * in the widget matches the current nullValue() then the returned value will be
+     * a null string.
      *
-     * @return Current text (Null string if it matches the nullValue property )
+     * @return Current text (or null string if it matches the nullValue() property )
+     * @see setValue()
      */
     QString value() const;
 
     /**
-     * Determine if the current text represents Null.
+     * Determine if the current text represents null.
      *
-     * @return True if the value is Null.
+     * @return True if the widget's value is null.
+     * @see nullValue()
      */
     bool isNull() const;
 
+  public slots:
+
+    /** Clears the widget and resets it to the null value.
+     * @see nullValue()
+     * @note added in QGIS 3.0
+     */
+    virtual void clearValue();
+
   signals:
+
+    /** Emitted when the widget is cleared
+     * @see clearValue()
+     */
     void cleared();
 
     /**
-     * Same as textChanged(const QString& ) but with support for Null values.
+     * Same as textChanged() but with support for null values.
      *
-     * @param value The current text or Null string if it matches the nullValue property.
+     * @param value The current text or null string if it matches the nullValue() property.
      */
     void valueChanged( const QString& value );