Skip to content
Permalink
Browse files
Merge pull request #3468 from nyalldawson/spin_box_v2
Rework Qgs(Double)SpinBox clear handling
  • Loading branch information
nyalldawson committed Sep 8, 2016
2 parents a90217d + f16b387 commit f52a9a00d898d8f005991e00e561ae73d4676af5
@@ -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 );
};
@@ -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 );
};
@@ -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 );

0 comments on commit f52a9a0

Please sign in to comment.