diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 1f16d5c820..6e3e3a0331 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -1,6 +1,7 @@ gtkaccelmap.sgml gtkactiongroup.sgml gtkaboutdialog.sgml +gtkadjustment.sgml gtkbbox.sgml gtkbox.sgml gtkbuilder.sgml diff --git a/docs/reference/gtk/tmpl/gtkadjustment.sgml b/docs/reference/gtk/tmpl/gtkadjustment.sgml deleted file mode 100644 index f41c2b3c79..0000000000 --- a/docs/reference/gtk/tmpl/gtkadjustment.sgml +++ /dev/null @@ -1,310 +0,0 @@ - -GtkAdjustment - - -A representation of an adjustable bounded value - - - -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 -#GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale). - - -The #GtkAdjustment object does not update the value itself. Instead -it is left up to the owner of the #GtkAdjustment to control the value. - - -The owner of the #GtkAdjustment typically calls the -gtk_adjustment_value_changed() and gtk_adjustment_changed() functions -after changing the value and its bounds. This results in the emission of the -"value_changed" or "changed" signal respectively. - - - - - - - - - - - - - - - -The #GtkAdjustment-struct struct contains the following fields. - - - - - - -#gdouble lower; -the minimum value. - - - -#gdouble upper; -the maximum value. - - - -#gdouble value; -the current value. - - - -#gdouble step_increment; -the increment to use to make minor changes to the value. -In a #GtkScrollbar this increment is used when the mouse is clicked on the -arrows at the top and bottom of the scrollbar, to scroll by a small amount. - - - - -#gdouble page_increment; -the increment to use to make major changes to the value. -In a #GtkScrollbar this increment is used when the mouse is clicked in the -trough, to scroll by a large amount. - - - - -#gdouble page_size; -the page size. -In a #GtkScrollbar this is the size of the area which is currently visible. - - - - - - - - - - -Emitted when one or more of the #GtkAdjustment fields have been changed, -other than the value field. - - -@adjustment: the object which received the signal. - - - -Emitted when the #GtkAdjustment value field has been changed. - - -@adjustment: the object which received the signal. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Creates a new #GtkAdjustment. - - -@value: the initial value. -@lower: the minimum value. -@upper: the maximum value. -@step_increment: the step increment. -@page_increment: the page increment. -@page_size: the page size. -@Returns: a new #GtkAdjustment. - - - - - - - -@adjustment: -@Returns: - - - - -Sets the #GtkAdjustment value. The value is clamped to lie between -adjustment->lower and -adjustment->upper. - - -Note that for adjustments which are used in a #GtkScrollbar, the effective -range of allowed values goes from adjustment->lower to -adjustment->upper - adjustment->page_size. - - -@adjustment: a #GtkAdjustment. -@value: the new value. - - - - -Updates the #GtkAdjustment @value to ensure that the range between @lower -and @upper is in the current page (i.e. between @value and @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 "changed" signal will be emitted if the value is changed. - - -@adjustment: a #GtkAdjustment. -@lower: the lower value. -@upper: the upper value. - - - - -Emits a "changed" signal from the #GtkAdjustment. -This is typically called by the owner of the #GtkAdjustment after it has -changed any of the #GtkAdjustment fields other than the value. - - -@adjustment: a #GtkAdjustment - - - - -Emits a "value_changed" signal from the #GtkAdjustment. -This is typically called by the owner of the #GtkAdjustment after it has -changed the #GtkAdjustment value field. - - -@adjustment: a #GtkAdjustment - - - - - - - -@adjustment: -@value: -@lower: -@upper: -@step_increment: -@page_increment: -@page_size: - - - - - - - -@adjustment: -@Returns: - - - - - - - -@adjustment: -@Returns: - - - - - - - -@adjustment: -@Returns: - - - - - - - -@adjustment: -@Returns: - - - - - - - -@adjustment: -@Returns: - - - - - - - -@adjustment: -@lower: - - - - - - - -@adjustment: -@page_increment: - - - - - - - -@adjustment: -@page_size: - - - - - - - -@adjustment: -@step_increment: - - - - - - - -@adjustment: -@upper: - - diff --git a/gtk/gtkadjustment.c b/gtk/gtkadjustment.c index 9c3b1d36dd..ae5e2926b2 100644 --- a/gtk/gtkadjustment.c +++ b/gtk/gtkadjustment.c @@ -31,6 +31,27 @@ #include "gtkintl.h" +/** + * SECTION:gtkadjustment + * @Short_description: A representation of an adjustable bounded value + * @Title: 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 + * #GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale). + * + * The #GtkAdjustment object does not update the value itself. Instead + * it is left up to the owner of the #GtkAdjustment to control the value. + * + * The owner of the #GtkAdjustment typically calls the + * gtk_adjustment_value_changed() and gtk_adjustment_changed() functions + * after changing the value and its bounds. This results in the emission of the + * #GtkAdjustment::value_changed or #GtkAdjustment::changed signal respectively. + */ + + enum { PROP_0, @@ -188,6 +209,13 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) 0.0, GTK_PARAM_READWRITE)); + /** + * GtkAdjustment::changed: + * @adjustment: the object which received the signal. + * + * Emitted when one or more of the #GtkAdjustment fields have been changed, + * other than the value field. + */ adjustment_signals[CHANGED] = g_signal_new (I_("changed"), G_OBJECT_CLASS_TYPE (class), @@ -197,6 +225,12 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class) _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * GtkAdjustment::value-changed: + * @adjustment: the object which received the signal. + * + * Emitted when the #GtkAdjustment value field has been changed. + */ adjustment_signals[VALUE_CHANGED] = g_signal_new (I_("value-changed"), G_OBJECT_CLASS_TYPE (class), @@ -318,6 +352,19 @@ gtk_adjustment_dispatch_properties_changed (GObject *object, } } +/** + * gtk_adjustment_new: + * @value: the initial value. + * @lower: the minimum value. + * @upper: the maximum value. + * @step_increment: the step increment. + * @page_increment: the page increment. + * @page_size: the page size. + * + * Creates a new #GtkAdjustment. + * + * Returns: a new #GtkAdjustment. + */ GtkAdjustment * gtk_adjustment_new (gdouble value, gdouble lower, @@ -353,6 +400,18 @@ gtk_adjustment_get_value (GtkAdjustment *adjustment) return adjustment->value; } +/** + * gtk_adjustment_set_value: + * @adjustment: a #GtkAdjustment. + * @value: the new value. + * + * Sets the #GtkAdjustment value. The value is clamped to lie between + * #GtkAdjustment.lower and #GtkAdjustment.upper. + * + * 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. + */ void gtk_adjustment_set_value (GtkAdjustment *adjustment, gdouble value) @@ -656,6 +715,14 @@ gtk_adjustment_configure (GtkAdjustment *adjustment, gtk_adjustment_value_changed (adjustment); } +/** + * gtk_adjustment_changed: + * @adjustment: a #GtkAdjustment + * + * Emits a #GtkAdjustment::changed signal from the #GtkAdjustment. + * This is typically called by the owner of the #GtkAdjustment after it has + * changed any of the #GtkAdjustment fields other than the value. + */ void gtk_adjustment_changed (GtkAdjustment *adjustment) { @@ -664,6 +731,14 @@ gtk_adjustment_changed (GtkAdjustment *adjustment) g_signal_emit (adjustment, adjustment_signals[CHANGED], 0); } +/** + * gtk_adjustment_value_changed: + * @adjustment: a #GtkAdjustment + * + * Emits a #GtkAdjustment::value_changed signal from the #GtkAdjustment. + * This is typically called by the owner of the #GtkAdjustment after it has + * changed the #GtkAdjustment value field. + */ void gtk_adjustment_value_changed (GtkAdjustment *adjustment) { @@ -673,6 +748,19 @@ gtk_adjustment_value_changed (GtkAdjustment *adjustment) g_object_notify (G_OBJECT (adjustment), "value"); } +/** + * gtk_adjustment_clamp_page: + * @adjustment: a #GtkAdjustment. + * @lower: the lower value. + * @upper: the upper value. + * + * Updates the #GtkAdjustment #GtkAdjustment.value 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. + * A #GtkAdjustment::changed signal will be emitted if the value is changed. + */ void gtk_adjustment_clamp_page (GtkAdjustment *adjustment, gdouble lower, diff --git a/gtk/gtkadjustment.h b/gtk/gtkadjustment.h index 7cac64292c..319953b342 100644 --- a/gtk/gtkadjustment.h +++ b/gtk/gtkadjustment.h @@ -46,6 +46,22 @@ G_BEGIN_DECLS typedef struct _GtkAdjustment GtkAdjustment; typedef struct _GtkAdjustmentClass GtkAdjustmentClass; +/** + * GtkAdjustment: + * @lower: the minimum value. + * @upper: the maximum value. + * @value: the current value. + * @step_increment: the increment to use to make minor changes to the @value. + * In a #GtkScrollbar this increment is used when the mouse is clicked on the + * arrows at the top and bottom of the scrollbar, to scroll by a small amount. + * @page_increment: the increment to use to make major changes to the @value. + * In a #GtkScrollbar this increment is used when the mouse is clicked in the + * trough, to scroll by a large amount. + * @page_size: In a #GtkScrollbar this is the size of the area which is currently + * visible. + * + * The #GtkAdjustment struct contains the following fields. + */ struct _GtkAdjustment { GInitiallyUnowned parent_instance;