From: Daniel Boles <dboles@src.gnome.org>
Date: Wed, 26 Apr 2017 11:18:12 +0000 (+0100)
Subject: Scale: Fix documentation of digits per last revert
X-Git-Tag: archive/raspbian/3.24.39-1+rpi1~1^2~65^2~39^2~610
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=1cd0a8de0b7041a28fb960bbb64507d3140ddeed;p=gtk%2B3.0.git

Scale: Fix documentation of digits per last revert

Revert doc changes that were for the behavioural change just reverted.

Add a clarifying note that, under the original behaviour, :digits only
rounds the Adjustment if :draw-value is TRUE at the time of the change.

https://bugzilla.gnome.org/show_bug.cgi?id=781605
https://bugzilla.gnome.org/show_bug.cgi?id=358970
---

diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 5f7720ac50..ea58d66185 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -762,17 +762,10 @@ gtk_scale_class_init (GtkScaleClass *class)
                   G_TYPE_STRING, 1,
                   G_TYPE_DOUBLE);
 
-  /**
-   * GtkScale:digits:
-   *
-   * The number of decimal places to which the value is rounded when it is
-   * changed. This also sets the number of digits shown in the displayed value
-   * when using the default handler for the #GtkScale::format-value signal.
-   */
   properties[PROP_DIGITS] =
       g_param_spec_int ("digits",
                         P_("Digits"),
-                        P_("The number of decimal places to which the value is rounded"),
+                        P_("The number of decimal places that are displayed in the value"),
                         -1, MAX_DIGITS,
                         1,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
@@ -1120,11 +1113,13 @@ gtk_scale_new_with_range (GtkOrientation orientation,
 /**
  * gtk_scale_set_digits:
  * @scale: a #GtkScale
- * @digits: the number of decimal places to which the value will be rounded
+ * @digits: the number of decimal places to display,
+ *     e.g. use 1 to display 1.0, 2 to display 1.00, etc
  *
- * Sets the number of decimal places to which the value is rounded when it is
- * changed. This also sets the number of digits shown in the displayed value
- * when using the default handler for the #GtkScale::format-value signal.
+ * Sets the number of decimal places that are displayed in the value. Also
+ * causes the value of the adjustment to be rounded to this number of digits
+ * whenever it is changed, so the retrieved value matches the displayed one, if
+ * #GtkScale:draw-value is TRUE at the time of the change.
  *
  * Note that rounding to a small number of digits can interfere with
  * the smooth autoscrolling that is built into #GtkScale. As an alternative,
@@ -1162,10 +1157,9 @@ gtk_scale_set_digits (GtkScale *scale,
  * gtk_scale_get_digits:
  * @scale: a #GtkScale
  *
- * Gets the number of decimal places to which the value is rounded on change.
- * This number is also used by the default #GtkScale::format-value handler.
+ * Gets the number of decimal places that are displayed in the value.
  *
- * Returns: the number of decimal places
+ * Returns: the number of decimal places that are displayed
  */
 gint
 gtk_scale_get_digits (GtkScale *scale)
@@ -1963,7 +1957,8 @@ weed_out_neg_zero (gchar *str,
 }
 
 /*
- * Emits the #GtkScale::format-value signal.
+ * Emits #GtkScale:format-value signal to format the value;
+ * if no user signal handlers, falls back to a default format.
  *
  * Returns: formatted value
  */