AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

gtkadjustment: Move documentation to inline comments

Browse Source
This commit is contained in:
Javier Jardón 2010-10-23 00:16:27 +02:00
parent 96f2f2ff5b
commit 38dbb84095
4 changed files with 105 additions and 310 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -1,6 +1,7 @@
gtkaccelmap.sgml gtkaccelmap.sgml
gtkactiongroup.sgml gtkactiongroup.sgml
gtkaboutdialog.sgml gtkaboutdialog.sgml
gtkadjustment.sgml
gtkbbox.sgml gtkbbox.sgml
gtkbox.sgml gtkbox.sgml
gtkbuilder.sgml gtkbuilder.sgml

310
docs/reference/gtk/tmpl/gtkadjustment.sgml
View File

@ -1,310 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkAdjustment
<!-- ##### SECTION Short_Description ##### -->
A representation of an adjustable bounded value
<!-- ##### SECTION Long_Description ##### -->
<para>
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).
</para>
<para>
The #GtkAdjustment object does not update the value itself. Instead
it is left up to the owner of the #GtkAdjustment to control the value.
</para>
<para>
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
&quot;value_changed&quot; or &quot;changed&quot; signal respectively.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### STRUCT GtkAdjustment ##### -->
<para>
The #GtkAdjustment-struct struct contains the following fields.
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry>#gdouble lower;</entry>
<entry>the minimum value.</entry>
</row>
<row>
<entry>#gdouble upper;</entry>
<entry>the maximum value.</entry>
</row>
<row>
<entry>#gdouble value;</entry>
<entry>the current value.</entry>
</row>
<row>
<entry>#gdouble step_increment;</entry>
<entry>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.
</entry>
</row>
<row>
<entry>#gdouble page_increment;</entry>
<entry>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.
</entry>
</row>
<row>
<entry>#gdouble page_size;</entry>
<entry>the page size.
In a #GtkScrollbar this is the size of the area which is currently visible.
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<!-- ##### SIGNAL GtkAdjustment::changed ##### -->
<para>
Emitted when one or more of the #GtkAdjustment fields have been changed,
other than the value field.
</para>
@adjustment: the object which received the signal.
<!-- ##### SIGNAL GtkAdjustment::value-changed ##### -->
<para>
Emitted when the #GtkAdjustment value field has been changed.
</para>
@adjustment: the object which received the signal.
<!-- ##### ARG GtkAdjustment:lower ##### -->
<para>
</para>
<!-- ##### ARG GtkAdjustment:page-increment ##### -->
<para>
</para>
<!-- ##### ARG GtkAdjustment:page-size ##### -->
<para>
</para>
<!-- ##### ARG GtkAdjustment:step-increment ##### -->
<para>
</para>
<!-- ##### ARG GtkAdjustment:upper ##### -->
<para>
</para>
<!-- ##### ARG GtkAdjustment:value ##### -->
<para>
</para>
<!-- ##### FUNCTION gtk_adjustment_new ##### -->
<para>
Creates a new #GtkAdjustment.
</para>
@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.
<!-- ##### FUNCTION gtk_adjustment_get_value ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_set_value ##### -->
<para>
Sets the #GtkAdjustment value. The value is clamped to lie between
<literal>adjustment-&gt;lower</literal> and
<literal>adjustment-&gt;upper</literal>.
</para>
<para>
Note that for adjustments which are used in a #GtkScrollbar, the effective
range of allowed values goes from <literal>adjustment-&gt;lower</literal> to
<literal>adjustment-&gt;upper - adjustment-&gt;page_size</literal>.
</para>
@adjustment: a #GtkAdjustment.
@value: the new value.
<!-- ##### FUNCTION gtk_adjustment_clamp_page ##### -->
<para>
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 &quot;changed&quot; signal will be emitted if the value is changed.
</para>
@adjustment: a #GtkAdjustment.
@lower: the lower value.
@upper: the upper value.
<!-- ##### FUNCTION gtk_adjustment_changed ##### -->
<para>
Emits a &quot;changed&quot; 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.
</para>
@adjustment: a #GtkAdjustment
<!-- ##### FUNCTION gtk_adjustment_value_changed ##### -->
<para>
Emits a &quot;value_changed&quot; signal from the #GtkAdjustment.
This is typically called by the owner of the #GtkAdjustment after it has
changed the #GtkAdjustment value field.
</para>
@adjustment: a #GtkAdjustment
<!-- ##### FUNCTION gtk_adjustment_configure ##### -->
<para>
</para>
@adjustment:
@value:
@lower:
@upper:
@step_increment:
@page_increment:
@page_size:
<!-- ##### FUNCTION gtk_adjustment_get_lower ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_get_page_increment ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_get_page_size ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_get_step_increment ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_get_upper ##### -->
<para>
</para>
@adjustment:
@Returns:
<!-- ##### FUNCTION gtk_adjustment_set_lower ##### -->
<para>
</para>
@adjustment:
@lower:
<!-- ##### FUNCTION gtk_adjustment_set_page_increment ##### -->
<para>
</para>
@adjustment:
@page_increment:
<!-- ##### FUNCTION gtk_adjustment_set_page_size ##### -->
<para>
</para>
@adjustment:
@page_size:
<!-- ##### FUNCTION gtk_adjustment_set_step_increment ##### -->
<para>
</para>
@adjustment:
@step_increment:
<!-- ##### FUNCTION gtk_adjustment_set_upper ##### -->
<para>
</para>
@adjustment:
@upper:

88
gtk/gtkadjustment.c
View File

@ -31,6 +31,27 @@
#include "gtkintl.h" #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 enum
{ {
PROP_0, PROP_0,
@ -188,6 +209,13 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
0.0, 0.0,
GTK_PARAM_READWRITE)); 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] = adjustment_signals[CHANGED] =
g_signal_new (I_("changed"), g_signal_new (I_("changed"),
G_OBJECT_CLASS_TYPE (class), G_OBJECT_CLASS_TYPE (class),
@ -197,6 +225,12 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
_gtk_marshal_VOID__VOID, _gtk_marshal_VOID__VOID,
G_TYPE_NONE, 0); 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] = adjustment_signals[VALUE_CHANGED] =
g_signal_new (I_("value-changed"), g_signal_new (I_("value-changed"),
G_OBJECT_CLASS_TYPE (class), 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 * GtkAdjustment *
gtk_adjustment_new (gdouble value, gtk_adjustment_new (gdouble value,
gdouble lower, gdouble lower,
@ -353,6 +400,18 @@ gtk_adjustment_get_value (GtkAdjustment *adjustment)
return adjustment->value; 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 void
gtk_adjustment_set_value (GtkAdjustment *adjustment, gtk_adjustment_set_value (GtkAdjustment *adjustment,
gdouble value) gdouble value)
@ -656,6 +715,14 @@ gtk_adjustment_configure (GtkAdjustment *adjustment,
gtk_adjustment_value_changed (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 void
gtk_adjustment_changed (GtkAdjustment *adjustment) gtk_adjustment_changed (GtkAdjustment *adjustment)
{ {
@ -664,6 +731,14 @@ gtk_adjustment_changed (GtkAdjustment *adjustment)
g_signal_emit (adjustment, adjustment_signals[CHANGED], 0); 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 void
gtk_adjustment_value_changed (GtkAdjustment *adjustment) gtk_adjustment_value_changed (GtkAdjustment *adjustment)
{ {
@ -673,6 +748,19 @@ gtk_adjustment_value_changed (GtkAdjustment *adjustment)
g_object_notify (G_OBJECT (adjustment), "value"); 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 void
gtk_adjustment_clamp_page (GtkAdjustment *adjustment, gtk_adjustment_clamp_page (GtkAdjustment *adjustment,
gdouble lower, gdouble lower,

16
gtk/gtkadjustment.h
View File

@ -46,6 +46,22 @@ G_BEGIN_DECLS
typedef struct _GtkAdjustment GtkAdjustment; typedef struct _GtkAdjustment GtkAdjustment;
typedef struct _GtkAdjustmentClass GtkAdjustmentClass; 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 struct _GtkAdjustment
{ {
GInitiallyUnowned parent_instance; GInitiallyUnowned parent_instance;