diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c index 4a38c5d213..2d443ef2ee 100644 --- a/gtk/gtkscale.c +++ b/gtk/gtkscale.c @@ -50,24 +50,27 @@ * @Short_description: A slider widget for selecting a value from a range * @Title: GtkScale * - * A GtkScale is a slider control used to select a numeric value. - * To use it, you’ll probably want to investigate the methods on - * its base class, #GtkRange, in addition to the methods for GtkScale itself. - * To set the value of a scale, you would normally use gtk_range_set_value(). - * To detect changes to the value, you would normally use the - * #GtkRange::value-changed signal. + * A `GtkScale` is a slider control used to select a numeric value. * - * Note that using the same upper and lower bounds for the #GtkScale (through - * the #GtkRange methods) will hide the slider itself. This is useful for + * ![An example GtkScale](scales.png) + * + * To use it, you’ll probably want to investigate the methods on its base + * class, [class@GtkRange], in addition to the methods for `GtkScale` itself. + * To set the value of a scale, you would normally use [method@Gtk.Range.set_value]. + * To detect changes to the value, you would normally use the + * [signal@Gtk.Range::value-changed] signal. + * + * Note that using the same upper and lower bounds for the `GtkScale` (through + * the `GtkRange` methods) will hide the slider itself. This is useful for * applications that want to show an undeterminate value on the scale, without * changing the layout of the application (such as movie or music players). * * # GtkScale as GtkBuildable * - * GtkScale supports a custom element, which can contain multiple - * elements. The “value” and “position” attributes have the same - * meaning as gtk_scale_add_mark() parameters of the same name. If the - * element is not empty, its content is taken as the markup to show at + * `GtkScale` supports a custom element, which can contain multiple + * elements. The “value” and “position” attributes have the same + * meaning as [method@Gtk.Scale.add_mark] parameters of the same name. If + * the element is not empty, its content is taken as the markup to show at * the mark. It can be translated with the usual ”translatable” and * “context” attributes. * @@ -94,17 +97,17 @@ * ╰── slider * ]| * - * GtkScale has a main CSS node with name scale and a subnode for its contents, + * `GtkScale` has a main CSS node with name scale and a subnode for its contents, * with subnodes named trough and slider. * * The main node gets the style class .fine-tune added when the scale is in * 'fine-tuning' mode. * - * If the scale has an origin (see gtk_scale_set_has_origin()), there is a - * subnode with name highlight below the trough node that is used for rendering + * If the scale has an origin (see [method@Gtk.Scale.set_has_origin]), there is + * a subnode with name highlight below the trough node that is used for rendering * the highlighted part of the trough. * - * If the scale is showing a fill level (see gtk_range_set_show_fill_level()), + * If the scale is showing a fill level (see [method@Gtk.Range.set_show_fill_level]), * there is a subnode with name fill below the trough node that is used for * rendering the filled in part of the trough. * @@ -120,13 +123,13 @@ * The main CSS node gets the 'marks-before' and/or 'marks-after' style classes * added depending on what marks are present. * - * If the scale is displaying the value (see #GtkScale:draw-value), there is - * subnode with name value. This node will get the .top or .bottom style classes - * similar to the marks node. + * If the scale is displaying the value (see [property@Gtk.Scale:draw-value]), + * there is subnode with name value. This node will get the .top or .bottom style + * classes similar to the marks node. * * # Accessibility * - * GtkScale uses the #GTK_ACCESSIBLE_ROLE_SLIDER role. + * `GtkScale` uses the #GTK_ACCESSIBLE_ROLE_SLIDER role. */ @@ -670,6 +673,11 @@ gtk_scale_class_init (GtkScaleClass *class) class->get_layout_offsets = gtk_scale_real_get_layout_offsets; + /** + * GtkScale:digits: + * + * The number of decimal places that are displayed in the value. + */ properties[PROP_DIGITS] = g_param_spec_int ("digits", P_("Digits"), @@ -678,6 +686,11 @@ gtk_scale_class_init (GtkScaleClass *class) 1, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkScale:draw-value: + * + * Whether the current value is displayed as a string next to the slider. + */ properties[PROP_DRAW_VALUE] = g_param_spec_boolean ("draw-value", P_("Draw Value"), @@ -685,6 +698,11 @@ gtk_scale_class_init (GtkScaleClass *class) FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkScale:has-origin: + * + * Whether the scale has an origin. + */ properties[PROP_HAS_ORIGIN] = g_param_spec_boolean ("has-origin", P_("Has Origin"), @@ -692,6 +710,11 @@ gtk_scale_class_init (GtkScaleClass *class) TRUE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkScale:value-pos: + * + * The position in which the current value is displayed. + */ properties[PROP_VALUE_POS] = g_param_spec_enum ("value-pos", P_("Value Position"), @@ -904,13 +927,13 @@ gtk_scale_get_property (GObject *object, /** * gtk_scale_new: * @orientation: the scale’s orientation. - * @adjustment: (nullable): the #GtkAdjustment which sets the range - * of the scale, or %NULL to create a new adjustment. + * @adjustment: (nullable): the [class@Gtk.Adjustment] which sets + * the range of the scale, or %NULL to create a new adjustment. * - * Creates a new #GtkScale. + * Creates a new `GtkScale`. * - * Returns: a new #GtkScale - **/ + * Returns: a new `GtkScale` + */ GtkWidget * gtk_scale_new (GtkOrientation orientation, GtkAdjustment *adjustment) @@ -931,15 +954,17 @@ gtk_scale_new (GtkOrientation orientation, * @max: maximum value * @step: step increment (tick size) used with keyboard shortcuts * - * Creates a new scale widget with the given orientation that lets the + * Creates a new scale widget with a range from @min to @max. + * + * The returns scale will have the given orientation and will let the * user input a number between @min and @max (including @min and @max) - * with the increment @step. @step must be nonzero; it’s the distance + * with the increment @step. @step must be nonzero; it’s the distance * the slider moves when using the arrow keys to adjust the scale * value. * - * Note that the way in which the precision is derived works best if @step - * is a power of ten. If the resulting precision is not suitable for your - * needs, use gtk_scale_set_digits() to correct it. + * Note that the way in which the precision is derived works best if + * @step is a power of ten. If the resulting precision is not suitable + * for your needs, use [method@Gtk.Scale.set_digits] to correct it. * * Returns: a new #GtkScale */ @@ -977,19 +1002,21 @@ gtk_scale_new_with_range (GtkOrientation orientation, /** * gtk_scale_set_digits: - * @scale: a #GtkScale + * @scale: a `GtkScale` * @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 that are displayed in the value. Also - * causes the value of the adjustment to be rounded to this number of digits, - * so the retrieved value matches the displayed one, if #GtkScale:draw-value is - * %TRUE when the value changes. If you want to enforce rounding the value when - * #GtkScale:draw-value is %FALSE, you can set #GtkRange:round-digits instead. + * 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, so the retrieved value matches the displayed one, if + * [property@GtkScale:draw-value] is %TRUE when the value changes. If + * you want to enforce rounding the value when [property@GtkScale:draw-value] + * is %FALSE, you can set [property@GtkRange:round-digits] instead. * * Note that rounding to a small number of digits can interfere with - * the smooth autoscrolling that is built into #GtkScale. As an alternative, - * you can use gtk_scale_set_format_value_func() to format the displayed + * the smooth autoscrolling that is built into `GtkScale`. As an alternative, + * you can use [method@Gtk.Scale.set_format_value_func] to format the displayed * value yourself. */ void @@ -1019,7 +1046,7 @@ gtk_scale_set_digits (GtkScale *scale, /** * gtk_scale_get_digits: - * @scale: a #GtkScale + * @scale: a `GtkScale` * * Gets the number of decimal places that are displayed in the value. * @@ -1073,7 +1100,7 @@ update_value_position (GtkScale *scale) * @scale: a #GtkScale * @draw_value: %TRUE to draw the value * - * Specifies whether the current value is displayed as a string next + * Specifies whether the current value is displayed as a string next * to the slider. */ void @@ -1119,9 +1146,9 @@ gtk_scale_set_draw_value (GtkScale *scale, /** * gtk_scale_get_draw_value: - * @scale: a #GtkScale + * @scale: a `GtkScale` * - * Returns whether the current value is displayed as a string + * Returns whether the current value is displayed as a string * next to the slider. * * Returns: whether the current value is displayed as a string @@ -1138,12 +1165,14 @@ gtk_scale_get_draw_value (GtkScale *scale) /** * gtk_scale_set_has_origin: - * @scale: a #GtkScale + * @scale: a `GtkScale` * @has_origin: %TRUE if the scale has an origin - * - * If #GtkScale:has-origin is set to %TRUE (the default), the scale will - * highlight the part of the trough between the origin (bottom or left side) - * and the current value. + * + * Sets whether the scale has an origin. + * + * If [property@GtkScale:has-origin] is set to %TRUE (the default), + * the scale will highlight the part of the trough between the origin + * (bottom or left side) and the current value. */ void gtk_scale_set_has_origin (GtkScale *scale, @@ -1165,7 +1194,7 @@ gtk_scale_set_has_origin (GtkScale *scale, /** * gtk_scale_get_has_origin: - * @scale: a #GtkScale + * @scale: a `GtkScale` * * Returns whether the scale has an origin. * @@ -1181,7 +1210,7 @@ gtk_scale_get_has_origin (GtkScale *scale) /** * gtk_scale_set_value_pos: - * @scale: a #GtkScale + * @scale: a `GtkScale` * @pos: the position in which the current value is displayed * * Sets the position in which the current value is displayed. @@ -1207,7 +1236,7 @@ gtk_scale_set_value_pos (GtkScale *scale, /** * gtk_scale_get_value_pos: - * @scale: a #GtkScale + * @scale: a `GtkScale` * * Gets the position in which the current value is displayed. * @@ -1542,14 +1571,16 @@ gtk_scale_finalize (GObject *object) /** * gtk_scale_get_layout: - * @scale: A #GtkScale + * @scale: A `GtkScale` * - * Gets the #PangoLayout used to display the scale. The returned - * object is owned by the scale so does not need to be freed by - * the caller. + * Gets the `PangoLayout` used to display the scale. * - * Returns: (transfer none) (nullable): the #PangoLayout for this scale, - * or %NULL if the #GtkScale:draw-value property is %FALSE. + * The returned object is owned by the scale so does not need + * to be freed by the caller. + * + * Returns: (transfer none) (nullable): the [class@Pango.Layout] + * for this scale, or %NULL if the [property@GtkScale:draw-value] + * property is %FALSE. */ PangoLayout * gtk_scale_get_layout (GtkScale *scale) @@ -1570,12 +1601,13 @@ gtk_scale_get_layout (GtkScale *scale) * @x: (out) (allow-none): location to store X offset of layout, or %NULL * @y: (out) (allow-none): location to store Y offset of layout, or %NULL * - * Obtains the coordinates where the scale will draw the - * #PangoLayout representing the text in the scale. Remember - * when using the #PangoLayout function you need to convert to - * and from pixels using PANGO_PIXELS() or #PANGO_SCALE. + * Obtains the coordinates where the scale will draw the + * `PangoLayout` representing the text in the scale. * - * If the #GtkScale:draw-value property is %FALSE, the return + * Remember when using the `PangoLayout` function you need to + * convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. + * + * If the [property@GtkScale:draw-value] property is %FALSE, the return * values are undefined. */ void @@ -1614,9 +1646,9 @@ gtk_scale_mark_free (gpointer data) /** * gtk_scale_clear_marks: - * @scale: a #GtkScale - * - * Removes any marks that have been added with gtk_scale_add_mark(). + * @scale: a `GtkScale` + * + * Removes any marks that have been added. */ void gtk_scale_clear_marks (GtkScale *scale) @@ -1641,15 +1673,15 @@ gtk_scale_clear_marks (GtkScale *scale) /** * gtk_scale_add_mark: - * @scale: a #GtkScale + * @scale: a `GtkScale` * @value: the value at which the mark is placed, must be between * the lower and upper limits of the scales’ adjustment * @position: where to draw the mark. For a horizontal scale, #GTK_POS_TOP * and %GTK_POS_LEFT are drawn above the scale, anything else below. * For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to * the left of the scale, anything else to the right. - * @markup: (allow-none): Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL - * + * @markup: (allow-none): Text to be shown at the mark, using + * Pango markup, or %NULL * * Adds a mark at @value. * @@ -1659,7 +1691,7 @@ gtk_scale_clear_marks (GtkScale *scale) * * If @markup is not %NULL, text is shown next to the tick mark. * - * To remove marks from a scale, use gtk_scale_clear_marks(). + * To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. */ void gtk_scale_add_mark (GtkScale *scale, @@ -2015,17 +2047,19 @@ gtk_scale_buildable_custom_finished (GtkBuildable *buildable, /** * gtk_scale_set_format_value_func: - * @scale: a #GtkScale + * @scale: a `GtkScale` * @func: (nullable): function that formats the value * @user_data: (closure): user data to pass to @func * @destroy_notify: (nullable): destroy function for @user_data * - * @func allows you to change how the scale value is displayed. The given - * function will return an allocated string representing @value. - * That string will then be used to display the scale's value. + * @func allows you to change how the scale value is displayed. + * + * The given function will return an allocated string representing + * @value. That string will then be used to display the scale's value. * * If #NULL is passed as @func, the value will be displayed on - * its own, rounded according to the value of the #GtkScale:digits property. + * its own, rounded according to the value of the + * [property@GtkScale:digits] property. */ void gtk_scale_set_format_value_func (GtkScale *scale,