diff --git a/gtk/gtkadjustment.c b/gtk/gtkadjustment.c index 67713a7db0..168fbe71c9 100644 --- a/gtk/gtkadjustment.c +++ b/gtk/gtkadjustment.c @@ -31,17 +31,17 @@ /** - * SECTION:gtkadjustment - * @Short_description: A representation of an adjustable bounded value - * @Title: GtkAdjustment + * GtkAdjustment: * - * The #GtkAdjustment object represents a value which has an associated lower - * and upper bound, together with step and page increments, and a page size. - * It is used within several GTK widgets, including #GtkSpinButton, #GtkViewport, - * and #GtkRange (which is a base class for #GtkScrollbar and #GtkScale). + * The `GtkAdjustment` object represents a value which has an associated lower + * and upper bound. * - * The #GtkAdjustment object does not update the value itself. Instead - * it is left up to the owner of the #GtkAdjustment to control the value. + * It also contains step and page increments, and a page size. It is used + * within several GTK widgets, including [class@Gtk.SpinButton], + * [class@Gtk.Viewport], [class@Gtk.Scrollbar] and [class@Gtk.Scale]. + * + * The `GtkAdjustment` object does not update the value itself. Instead + * it is left up to the owner of the `GtkAdjustment` to control the value. */ @@ -130,7 +130,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) class->value_changed = NULL; /** - * GtkAdjustment:value: + * GtkAdjustment:value: (attributes org.gtk.Property.get=gtk_adjustment_get_value org.gtk.Property.set=gtk_adjustment_set_value) * * The value of the adjustment. */ @@ -143,7 +143,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) GTK_PARAM_READWRITE); /** - * GtkAdjustment:lower: + * GtkAdjustment:lower: (attributes org.gtk.Property.get=gtk_adjustment_get_lower org.gtk.Property.set=gtk_adjustment_set_lower) * * The minimum value of the adjustment. */ @@ -156,11 +156,11 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) GTK_PARAM_READWRITE); /** - * GtkAdjustment:upper: + * GtkAdjustment:upper: (attributes org.gtk.Property.get=gtk_adjustment_get_upper org.gtk.Property.set=gtk_adjustment_set_upper) * * The maximum value of the adjustment. - * Note that values will be restricted by - * `upper - page-size` if the page-size + * + * Note that values will be restricted by `upper - page-size` if the page-size * property is nonzero. */ adjustment_props[PROP_UPPER] = @@ -172,7 +172,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) GTK_PARAM_READWRITE); /** - * GtkAdjustment:step-increment: + * GtkAdjustment:step-increment: (attributes org.gtk.Property.get=gtk_adjustment_get_step_increment org.gtk.Property.set=gtk_adjustment_set_step_increment) * * The step increment of the adjustment. */ @@ -185,7 +185,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) GTK_PARAM_READWRITE); /** - * GtkAdjustment:page-increment: + * GtkAdjustment:page-increment: (attributes org.gtk.Property.get=gtk_adjustment_get_page_increment org.gtk.Property.set=gtk_adjustment_set_page_increment) * * The page increment of the adjustment. */ @@ -198,12 +198,13 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) GTK_PARAM_READWRITE); /** - * GtkAdjustment:page-size: + * GtkAdjustment:page-size: (attributes org.gtk.Property.get=gtk_adjustment_get_page_size org.gtk.Property.set=gtk_adjustment_set_page_size) * * The page size of the adjustment. + * * Note that the page-size is irrelevant and should be set to zero * if the adjustment is used for a simple scalar value, e.g. in a - * #GtkSpinButton. + * `GtkSpinButton`. */ adjustment_props[PROP_PAGE_SIZE] = g_param_spec_double ("page-size", @@ -219,8 +220,11 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) * GtkAdjustment::changed: * @adjustment: the object which received the signal * - * Emitted when one or more of the #GtkAdjustment properties have been - * changed, other than the #GtkAdjustment:value property. + * Emitted when one or more of the `GtkAdjustment` properties have been + * changed. + * + * Note that the [property@Gtk.Adjustment:value] property is + * covered by the [signal@Gtk.Adjustment::value-changed] signal. */ adjustment_signals[CHANGED] = g_signal_new (I_("changed"), @@ -235,7 +239,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) * GtkAdjustment::value-changed: * @adjustment: the object which received the signal * - * Emitted when the #GtkAdjustment:value property has been changed. + * Emitted when the value has been changed. */ adjustment_signals[VALUE_CHANGED] = g_signal_new (I_("value-changed"), @@ -368,9 +372,9 @@ gtk_adjustment_dispatch_properties_changed (GObject *object, * @page_increment: the page increment * @page_size: the page size * - * Creates a new #GtkAdjustment. + * Creates a new `GtkAdjustment`. * - * Returns: a new #GtkAdjustment + * Returns: a new `GtkAdjustment` */ GtkAdjustment * gtk_adjustment_new (double value, @@ -391,14 +395,13 @@ gtk_adjustment_new (double value, } /** - * gtk_adjustment_get_value: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_value: (attributes org.gtk.Method.get_property=value) + * @adjustment: a `GtkAdjustment` * * Gets the current value of the adjustment. - * See gtk_adjustment_set_value(). * * Returns: The current value of the adjustment - **/ + */ double gtk_adjustment_get_value (GtkAdjustment *adjustment) { @@ -530,16 +533,19 @@ gtk_adjustment_set_value_internal (GtkAdjustment *adjustment, } /** - * gtk_adjustment_set_value: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_value: (attributes org.gtk.Method.set_property=value) + * @adjustment: a `GtkAdjustment` * @value: the new value * - * Sets the #GtkAdjustment value. The value is clamped to lie between - * #GtkAdjustment:lower and #GtkAdjustment:upper. + * Sets the `GtkAdjustment` value. * - * Note that for adjustments which are used in a #GtkScrollbar, the - * effective range of allowed values goes from #GtkAdjustment:lower to - * #GtkAdjustment:upper - #GtkAdjustment:page-size. + * The value is clamped to lie between [property@Gtk.Adjustment:lower] + * and [property@Gtk.Adjustment:upper]. + * + * Note that for adjustments which are used in a `GtkScrollbar`, + * the effective range of allowed values goes from + * [property@Gtk.Adjustment:lower] to + * [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size]. */ void gtk_adjustment_set_value (GtkAdjustment *adjustment, @@ -560,8 +566,8 @@ gtk_adjustment_animate_to_value (GtkAdjustment *adjustment, } /** - * gtk_adjustment_get_lower: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_lower: (attributes org.gtk.Method.get_property=lower) + * @adjustment: a `GtkAdjustment` * * Retrieves the minimum value of the adjustment. * @@ -578,24 +584,24 @@ gtk_adjustment_get_lower (GtkAdjustment *adjustment) } /** - * gtk_adjustment_set_lower: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_lower: (attributes org.gtk.Method.set_property=lower) + * @adjustment: a `GtkAdjustment` * @lower: the new minimum value * * Sets the minimum value of the adjustment. * * When setting multiple adjustment properties via their individual - * setters, multiple #GtkAdjustment::changed signals will be emitted. - * However, since the emission of the #GtkAdjustment::changed signal - * is tied to the emission of the #GObject::notify signals of the changed - * properties, it’s possible to compress the #GtkAdjustment::changed - * signals into one by calling g_object_freeze_notify() and - * g_object_thaw_notify() around the calls to the individual setters. + * setters, multiple [signal@Gtk.Adjustment::changed] signals will + * be emitted. However, since the emission of the + * [signal@Gtk.Adjustment::changed] signal is tied to the emission + * of the ::notify signals of the changed properties, it’s possible + * to compress the [signal@Gtk.Adjustment::changed] signals into one + * by calling g_object_freeze_notify() and g_object_thaw_notify() + * around the calls to the individual setters. * * Alternatively, using a single g_object_set() for all the properties - * to change, or using gtk_adjustment_configure() has the same effect - * of compressing #GtkAdjustment::changed emissions. - **/ + * to change, or using [method@Gtk.Adjustment.configure] has the same effect. + */ void gtk_adjustment_set_lower (GtkAdjustment *adjustment, double lower) @@ -612,13 +618,13 @@ gtk_adjustment_set_lower (GtkAdjustment *adjustment, } /** - * gtk_adjustment_get_upper: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_upper: (attributes org.gtk.Method.get_property=upper) + * @adjustment: a `GtkAdjustment` * * Retrieves the maximum value of the adjustment. * * Returns: The current maximum value of the adjustment - **/ + */ double gtk_adjustment_get_upper (GtkAdjustment *adjustment) { @@ -630,8 +636,8 @@ gtk_adjustment_get_upper (GtkAdjustment *adjustment) } /** - * gtk_adjustment_set_upper: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_upper: (attributes org.gtk.Method.set_property=upper) + * @adjustment: a `GtkAdjustment` * @upper: the new maximum value * * Sets the maximum value of the adjustment. @@ -639,10 +645,10 @@ gtk_adjustment_get_upper (GtkAdjustment *adjustment) * Note that values will be restricted by `upper - page-size` * if the page-size property is nonzero. * - * See gtk_adjustment_set_lower() about how to compress multiple - * emissions of the #GtkAdjustment::changed signal when setting - * multiple adjustment properties. - **/ + * See [method@Gtk.Adjustment.set_lower] about how to compress + * multiple emissions of the [signal@Gtk.Adjustment::changed] + * signal when setting multiple adjustment properties. + */ void gtk_adjustment_set_upper (GtkAdjustment *adjustment, double upper) @@ -659,13 +665,13 @@ gtk_adjustment_set_upper (GtkAdjustment *adjustment, } /** - * gtk_adjustment_get_step_increment: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_step_increment: (attributes org.gtk.Method.get_property=step-increment) + * @adjustment: a `GtkAdjustment` * * Retrieves the step increment of the adjustment. * * Returns: The current step increment of the adjustment. - **/ + */ double gtk_adjustment_get_step_increment (GtkAdjustment *adjustment) { @@ -677,16 +683,16 @@ gtk_adjustment_get_step_increment (GtkAdjustment *adjustment) } /** - * gtk_adjustment_set_step_increment: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_step_increment: (attributes org.gtk.Method.set_property=step-increment) + * @adjustment: a `GtkAdjustment` * @step_increment: the new step increment * * Sets the step increment of the adjustment. * - * See gtk_adjustment_set_lower() about how to compress multiple - * emissions of the #GtkAdjustment::changed signal when setting - * multiple adjustment properties. - **/ + * See [method@Gtk.Adjustment.set_lower] about how to compress + * multiple emissions of the [signal@Gtk.Adjustment::changed] + * signal when setting multiple adjustment properties. + */ void gtk_adjustment_set_step_increment (GtkAdjustment *adjustment, double step_increment) @@ -703,8 +709,8 @@ gtk_adjustment_set_step_increment (GtkAdjustment *adjustment, } /** - * gtk_adjustment_get_page_increment: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_page_increment: (attributes org.gtk.Method.get_property=page-increment) + * @adjustment: a `GtkAdjustment` * * Retrieves the page increment of the adjustment. * @@ -721,16 +727,16 @@ gtk_adjustment_get_page_increment (GtkAdjustment *adjustment) } /** - * gtk_adjustment_set_page_increment: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_page_increment: (attributes org.gtk.Method.set_property=page-increment) + * @adjustment: a `GtkAdjustment` * @page_increment: the new page increment * * Sets the page increment of the adjustment. * - * See gtk_adjustment_set_lower() about how to compress multiple - * emissions of the #GtkAdjustment::changed signal when setting - * multiple adjustment properties. - **/ + * See [method@Gtk.Adjustment.set_lower] about how to compress + * multiple emissions of the [signal@Gtk.Adjustment::changed] + * signal when setting multiple adjustment properties. + */ void gtk_adjustment_set_page_increment (GtkAdjustment *adjustment, double page_increment) @@ -747,8 +753,8 @@ gtk_adjustment_set_page_increment (GtkAdjustment *adjustment, } /** - * gtk_adjustment_get_page_size: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_get_page_size: (attributes org.gtk.Method.get_property=page-size) + * @adjustment: a `GtkAdjustment` * * Retrieves the page size of the adjustment. * @@ -765,16 +771,16 @@ gtk_adjustment_get_page_size (GtkAdjustment *adjustment) } /** - * gtk_adjustment_set_page_size: - * @adjustment: a #GtkAdjustment + * gtk_adjustment_set_page_size: (attributes org.gtk.Method.set_property=page-size) + * @adjustment: a `GtkAdjustment` * @page_size: the new page size * * Sets the page size of the adjustment. * - * See gtk_adjustment_set_lower() about how to compress multiple - * emissions of the GtkAdjustment::changed signal when setting - * multiple adjustment properties. - **/ + * See [method@Gtk.Adjustment.set_lower] about how to compress + * multiple emissions of the [signal@Gtk.Adjustment::changed] + * signal when setting multiple adjustment properties. + */ void gtk_adjustment_set_page_size (GtkAdjustment *adjustment, double page_size) @@ -792,7 +798,7 @@ gtk_adjustment_set_page_size (GtkAdjustment *adjustment, /** * gtk_adjustment_configure: - * @adjustment: a #GtkAdjustment + * @adjustment: a `GtkAdjustment` * @value: the new value * @lower: the new minimum value * @upper: the new maximum value @@ -803,10 +809,11 @@ gtk_adjustment_set_page_size (GtkAdjustment *adjustment, * Sets all properties of the adjustment at once. * * Use this function to avoid multiple emissions of the - * #GtkAdjustment::changed signal. See gtk_adjustment_set_lower() - * for an alternative way of compressing multiple emissions of - * #GtkAdjustment::changed into one. - **/ + * [signal@Gtk.Adjustment::changed] signal. See + * [method@Gtk.Adjustment.set_lower] for an alternative + * way of compressing multiple emissions of + * [signal@Gtk.Adjustment::changed] into one. + */ void gtk_adjustment_configure (GtkAdjustment *adjustment, double value, @@ -853,17 +860,19 @@ gtk_adjustment_configure (GtkAdjustment *adjustment, /** * gtk_adjustment_clamp_page: - * @adjustment: a #GtkAdjustment + * @adjustment: a `GtkAdjustment` * @lower: the lower value * @upper: the upper value * - * Updates the #GtkAdjustment:value property to ensure that the range - * between @lower and @upper is in the current page (i.e. between - * #GtkAdjustment:value and #GtkAdjustment:value + #GtkAdjustment:page-size). - * If the range is larger than the page size, then only the start of it will - * be in the current page. + * Updates the value property to ensure that the range + * between @lower and @upper is in the current page. * - * A #GtkAdjustment::value-changed signal will be emitted if the value is changed. + * The current page goes from `value` to `value` + `page-size`. + * If the range is larger than the page size, then only the + * start of it will be in the current page. + * + * A [signal@Gtk.Adjustment::value-changed] signal will be emitted + * if the value is changed. */ void gtk_adjustment_clamp_page (GtkAdjustment *adjustment, @@ -897,7 +906,7 @@ gtk_adjustment_clamp_page (GtkAdjustment *adjustment, /** * gtk_adjustment_get_minimum_increment: - * @adjustment: a #GtkAdjustment + * @adjustment: a `GtkAdjustment` * * Gets the smaller of step increment and page increment. * diff --git a/gtk/gtkadjustment.h b/gtk/gtkadjustment.h index 997c2b4df4..7f5ce89a34 100644 --- a/gtk/gtkadjustment.h +++ b/gtk/gtkadjustment.h @@ -44,12 +44,6 @@ G_BEGIN_DECLS typedef struct _GtkAdjustmentClass GtkAdjustmentClass; -/** - * GtkAdjustment: - * - * The #GtkAdjustment-struct contains only private fields and - * should not be directly accessed. - */ struct _GtkAdjustment { GInitiallyUnowned parent_instance;