feat(ColorWidget): Set color component as float

troopa81 · Aug 12, 2024 · 6ec40ca · 6ec40ca
1 parent c4e0b6a
commit 6ec40ca
Show file tree

Hide file tree

Showing 4 changed files with 521 additions and 252 deletions.
diff --git a/python/PyQt6/gui/auto_generated/qgscolorwidgets.sip.in b/python/PyQt6/gui/auto_generated/qgscolorwidgets.sip.in
@@ -66,7 +66,7 @@ Returns the color component which the widget controls
 .. seealso:: :py:func:`setComponent`
 %End
 
-    int componentValue() const;
+ int componentValue() const;
 %Docstring
 Returns the current value of the widget's color component
 
@@ -76,6 +76,23 @@ Returns the current value of the widget's color component
 .. seealso:: :py:func:`setComponentValue`
 
 .. seealso:: :py:func:`component`
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.componentValueF` instead.
+%End
+
+    float componentValueF() const;
+%Docstring
+Returns the current value of the widget's color component
+
+:return: value of color component, or -1 if widget has multiple components or an invalid color
+         set
+
+.. seealso:: :py:func:`setComponentValueF`
+
+.. seealso:: :py:func:`component`
+
+.. versionadded:: 3.40
 %End
 
     static QPixmap createDragIcon( const QColor &color );
@@ -106,12 +123,12 @@ Sets the color component which the widget controls
 .. seealso:: :py:func:`component`
 %End
 
-    virtual void setComponentValue( int value );
+ virtual void setComponentValue( int value );
 %Docstring
 Alters the widget's color by setting the value for the widget's color component
 
-:param value: value for widget's color component. This value is automatically
-              clipped to the range of valid values for the color component.
+:param value: value for widget's color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`.
+              This value is automatically clipped to the range of valid values for the color component.
 
 .. seealso:: :py:func:`componentValue`
 
@@ -121,6 +138,28 @@ Alters the widget's color by setting the value for the widget's color component
 
    this method has no effect if the widget is set to the QgsColorWidget.Multiple
    component
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.setComponentValueF` instead.
+%End
+
+    virtual void setComponentValueF( float value );
+%Docstring
+Alters the widget's color by setting the value for the widget's color component
+
+:param value: value for widget's color component in the range 0.0-1.0.
+              This value is automatically clipped to the range 0.0-1.0.
+
+.. seealso:: :py:func:`componentValue`
+
+.. seealso:: :py:func:`setComponent`
+
+.. note::
+
+   this method has no effect if the widget is set to the QgsColorWidget.Multiple
+   component
+
+.. versionadded:: 3.40
 %End
 
   signals:
@@ -156,24 +195,55 @@ Returns the range of valid values a color component
 :return: maximum value allowed for color component
 %End
 
-    int componentValue( ColorComponent component ) const;
+ int componentValue( ColorComponent component ) const;
+%Docstring
+Returns the value of a component of the widget's current color. This method correctly
+handles hue values when the color has an ambiguous hue (e.g., black or white shades)
+
+:param component: color component to return
+
+:return: value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`,
+         or -1 if widget has an invalid color set
+
+.. seealso:: :py:func:`hue`
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.componentValueF` instead.
+%End
+
+    float componentValueF( ColorComponent component ) const;
 %Docstring
 Returns the value of a component of the widget's current color. This method correctly
 handles hue values when the color has an ambiguous hue (e.g., black or white shades)
 
 :param component: color component to return
 
-:return: value of color component, or -1 if widget has an invalid color set
+:return: value of color component in the range 0-1.0, or -1 if widget has an invalid color set
 
 .. seealso:: :py:func:`hue`
+
+.. versionadded:: 3.40
 %End
 
-    int hue() const;
+ int hue() const;
 %Docstring
 Returns the hue for the widget. This may differ from the hue for the QColor returned by :py:func:`~QgsColorWidget.color`,
 as QColor returns a hue of -1 if the color's hue is ambiguous (e.g., if the saturation is zero).
 
-:return: explicitly set hue for widget
+:return: explicitly set hue for widget in the range 0-359
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.hueF` instead.
+%End
+
+    float hueF() const;
+%Docstring
+Returns the hue for the widget. This may differ from the hue for the QColor returned by :py:func:`~QgsColorWidget.color`,
+as QColor returns a hue of -1 if the color's hue is ambiguous (e.g., if the saturation is zero).
+
+:return: explicitly set hue for widget in the range 0-1.0
+
+.. versionadded:: 3.40
 %End
 
     static void alterColor( QColor &color, QgsColorWidget::ColorComponent component, int newValue );
@@ -182,8 +252,23 @@ Alters a color by modifying the value of a specific color component
 
 :param color: color to alter
 :param component: color component to alter
-:param newValue: new value of color component. Values are automatically clipped to a
+:param newValue: new value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`. Values are automatically clipped to a
                  valid range for the color component.
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.alterColorF` instead.
+%End
+
+    static void alterColorF( QColor &color, QgsColorWidget::ColorComponent component, float newValue );
+%Docstring
+Alters a color by modifying the value of a specific color component
+
+:param color: color to alter
+:param component: color component to alter
+:param newValue: new value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`. Values are automatically clipped to a
+                 valid range for the color component.
+
+.. versionadded:: 3.40
 %End
 
     QColor::Spec colorSpec() const;
@@ -476,11 +561,23 @@ Sets the size for drawing the triangular markers on the ramp
 
   signals:
 
-    void valueChanged( int value );
+ void valueChanged( int value );
 %Docstring
 Emitted when the widget's color component value changes
 
 :param value: new value of color component
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorRampWidget.valueChangedF` instead.
+%End
+
+    void valueChangedF( float value );
+%Docstring
+Emitted when the widget's color component value changes
+
+:param value: new value of color component
+
+.. versionadded:: 3.40
 %End
 
   protected:
@@ -521,7 +618,7 @@ Construct a new color slider widget.
 
     virtual void setComponent( ColorComponent component );
 
-    virtual void setComponentValue( int value );
+    virtual void setComponentValueF( float value );
 
     virtual void setColor( const QColor &color, bool emitSignals = false );
 

diff --git a/python/gui/auto_generated/qgscolorwidgets.sip.in b/python/gui/auto_generated/qgscolorwidgets.sip.in
@@ -66,7 +66,7 @@ Returns the color component which the widget controls
 .. seealso:: :py:func:`setComponent`
 %End
 
-    int componentValue() const;
+ int componentValue() const;
 %Docstring
 Returns the current value of the widget's color component
 
@@ -76,6 +76,23 @@ Returns the current value of the widget's color component
 .. seealso:: :py:func:`setComponentValue`
 
 .. seealso:: :py:func:`component`
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.componentValueF` instead.
+%End
+
+    float componentValueF() const;
+%Docstring
+Returns the current value of the widget's color component
+
+:return: value of color component, or -1 if widget has multiple components or an invalid color
+         set
+
+.. seealso:: :py:func:`setComponentValueF`
+
+.. seealso:: :py:func:`component`
+
+.. versionadded:: 3.40
 %End
 
     static QPixmap createDragIcon( const QColor &color );
@@ -106,12 +123,12 @@ Sets the color component which the widget controls
 .. seealso:: :py:func:`component`
 %End
 
-    virtual void setComponentValue( int value );
+ virtual void setComponentValue( int value );
 %Docstring
 Alters the widget's color by setting the value for the widget's color component
 
-:param value: value for widget's color component. This value is automatically
-              clipped to the range of valid values for the color component.
+:param value: value for widget's color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`.
+              This value is automatically clipped to the range of valid values for the color component.
 
 .. seealso:: :py:func:`componentValue`
 
@@ -121,6 +138,28 @@ Alters the widget's color by setting the value for the widget's color component
 
    this method has no effect if the widget is set to the QgsColorWidget.Multiple
    component
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.setComponentValueF` instead.
+%End
+
+    virtual void setComponentValueF( float value );
+%Docstring
+Alters the widget's color by setting the value for the widget's color component
+
+:param value: value for widget's color component in the range 0.0-1.0.
+              This value is automatically clipped to the range 0.0-1.0.
+
+.. seealso:: :py:func:`componentValue`
+
+.. seealso:: :py:func:`setComponent`
+
+.. note::
+
+   this method has no effect if the widget is set to the QgsColorWidget.Multiple
+   component
+
+.. versionadded:: 3.40
 %End
 
   signals:
@@ -156,24 +195,55 @@ Returns the range of valid values a color component
 :return: maximum value allowed for color component
 %End
 
-    int componentValue( ColorComponent component ) const;
+ int componentValue( ColorComponent component ) const;
+%Docstring
+Returns the value of a component of the widget's current color. This method correctly
+handles hue values when the color has an ambiguous hue (e.g., black or white shades)
+
+:param component: color component to return
+
+:return: value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`,
+         or -1 if widget has an invalid color set
+
+.. seealso:: :py:func:`hue`
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.componentValueF` instead.
+%End
+
+    float componentValueF( ColorComponent component ) const;
 %Docstring
 Returns the value of a component of the widget's current color. This method correctly
 handles hue values when the color has an ambiguous hue (e.g., black or white shades)
 
 :param component: color component to return
 
-:return: value of color component, or -1 if widget has an invalid color set
+:return: value of color component in the range 0-1.0, or -1 if widget has an invalid color set
 
 .. seealso:: :py:func:`hue`
+
+.. versionadded:: 3.40
 %End
 
-    int hue() const;
+ int hue() const;
 %Docstring
 Returns the hue for the widget. This may differ from the hue for the QColor returned by :py:func:`~QgsColorWidget.color`,
 as QColor returns a hue of -1 if the color's hue is ambiguous (e.g., if the saturation is zero).
 
-:return: explicitly set hue for widget
+:return: explicitly set hue for widget in the range 0-359
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.hueF` instead.
+%End
+
+    float hueF() const;
+%Docstring
+Returns the hue for the widget. This may differ from the hue for the QColor returned by :py:func:`~QgsColorWidget.color`,
+as QColor returns a hue of -1 if the color's hue is ambiguous (e.g., if the saturation is zero).
+
+:return: explicitly set hue for widget in the range 0-1.0
+
+.. versionadded:: 3.40
 %End
 
     static void alterColor( QColor &color, QgsColorWidget::ColorComponent component, int newValue );
@@ -182,8 +252,23 @@ Alters a color by modifying the value of a specific color component
 
 :param color: color to alter
 :param component: color component to alter
-:param newValue: new value of color component. Values are automatically clipped to a
+:param newValue: new value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`. Values are automatically clipped to a
                  valid range for the color component.
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorWidget.alterColorF` instead.
+%End
+
+    static void alterColorF( QColor &color, QgsColorWidget::ColorComponent component, float newValue );
+%Docstring
+Alters a color by modifying the value of a specific color component
+
+:param color: color to alter
+:param component: color component to alter
+:param newValue: new value of color component in the range between 0 and the value returned by :py:func:`~QgsColorWidget.componentRange`. Values are automatically clipped to a
+                 valid range for the color component.
+
+.. versionadded:: 3.40
 %End
 
     QColor::Spec colorSpec() const;
@@ -476,11 +561,23 @@ Sets the size for drawing the triangular markers on the ramp
 
   signals:
 
-    void valueChanged( int value );
+ void valueChanged( int value );
 %Docstring
 Emitted when the widget's color component value changes
 
 :param value: new value of color component
+
+.. deprecated:: QGIS 3.40.
+   Use :py:func:`~QgsColorRampWidget.valueChangedF` instead.
+%End
+
+    void valueChangedF( float value );
+%Docstring
+Emitted when the widget's color component value changes
+
+:param value: new value of color component
+
+.. versionadded:: 3.40
 %End
 
   protected:
@@ -521,7 +618,7 @@ Construct a new color slider widget.
 
     virtual void setComponent( ColorComponent component );
 
-    virtual void setComponentValue( int value );
+    virtual void setComponentValueF( float value );
 
     virtual void setColor( const QColor &color, bool emitSignals = false );