Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkadjustment.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkAdjustment
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A GtkObject representing an adjustable bounded value
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkAdjustment object represents a value which has an associated lower
  10 and upper bound, together with step and page increments, and a page size.
  11 It is used within several GTK+ widgets, including
  12 #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for
  13 #GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale).
  14 </para>
  15 <para>
  16 The #GtkAdjustment object does not update the value itself. Instead
  17 it is left up to the owner of the #GtkAdjustment to control the value.
  18 </para>
  19 <para>
  20 The owner of the #GtkAdjustment typically calls the
  21 gtk_adjustment_value_changed() and gtk_adjustment_changed() functions
  22 after changing the value and its bounds. This results in the emission of the
  23 &quot;value_changed&quot; or &quot;changed&quot; signal respectively.
  24 </para>
  25
  26 <!-- ##### SECTION See_Also ##### -->
  27 <para>
  28
  29 </para>
  30
  31 <!-- ##### STRUCT GtkAdjustment ##### -->
  32 <para>
  33 The #GtkAdjustment-struct struct contains the following fields.
  34
  35 <informaltable pgwide="1" frame="none" role="struct">
  36 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
  37 <tbody>
  38
  39 <row>
  40 <entry>#gdouble lower;</entry>
  41 <entry>the minimum value.</entry>
  42 </row>
  43
  44 <row>
  45 <entry>#gdouble upper;</entry>
  46 <entry>the maximum value.</entry>
  47 </row>
  48
  49 <row>
  50 <entry>#gdouble value;</entry>
  51 <entry>the current value.</entry>
  52 </row>
  53
  54 <row>
  55 <entry>#gdouble step_increment;</entry>
  56 <entry>the increment to use to make minor changes to the value.
  57 In a #GtkScrollbar this increment is used when the mouse is clicked on the
  58 arrows at the top and bottom of the scrollbar, to scroll by a small amount.
  59 </entry>
  60 </row>
  61
  62 <row>
  63 <entry>#gdouble page_increment;</entry>
  64 <entry>the increment to use to make major changes to the value.
  65 In a #GtkScrollbar this increment is used when the mouse is clicked in the
  66 trough, to scroll by a large amount.
  67 </entry>
  68 </row>
  69
  70 <row>
  71 <entry>#gdouble page_size;</entry>
  72 <entry>the page size.
  73 In a #GtkScrollbar this is the size of the area which is currently visible.
  74 </entry>
  75 </row>
  76
  77 </tbody></tgroup></informaltable>
  78
  79 </para>
  80
  81
  82 <!-- ##### SIGNAL GtkAdjustment::changed ##### -->
  83 <para>
  84 Emitted when one or more of the #GtkAdjustment fields have been changed,
  85 other than the value field.
  86 </para>
  87
  88 @adjustment: the object which received the signal.
  89
  90 <!-- ##### SIGNAL GtkAdjustment::value-changed ##### -->
  91 <para>
  92 Emitted when the #GtkAdjustment value field has been changed.
  93 </para>
  94
  95 @adjustment: the object which received the signal.
  96
  97 <!-- ##### ARG GtkAdjustment:lower ##### -->
  98 <para>
  99
 100 </para>
 101
 102 <!-- ##### ARG GtkAdjustment:page-increment ##### -->
 103 <para>
 104
 105 </para>
 106
 107 <!-- ##### ARG GtkAdjustment:page-size ##### -->
 108 <para>
 109
 110 </para>
 111
 112 <!-- ##### ARG GtkAdjustment:step-increment ##### -->
 113 <para>
 114
 115 </para>
 116
 117 <!-- ##### ARG GtkAdjustment:upper ##### -->
 118 <para>
 119
 120 </para>
 121
 122 <!-- ##### ARG GtkAdjustment:value ##### -->
 123 <para>
 124
 125 </para>
 126
 127 <!-- ##### FUNCTION gtk_adjustment_new ##### -->
 128 <para>
 129 Creates a new #GtkAdjustment.
 130 </para>
 131
 132 @value: the initial value.
 133 @lower: the minimum value.
 134 @upper: the maximum value.
 135 @step_increment: the step increment.
 136 @page_increment: the page increment.
 137 @page_size: the page size.
 138 @Returns: a new #GtkAdjustment.
 139
 140
 141 <!-- ##### FUNCTION gtk_adjustment_get_value ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @adjustment:
 147 @Returns:
 148
 149
 150 <!-- ##### FUNCTION gtk_adjustment_set_value ##### -->
 151 <para>
 152 Sets the #GtkAdjustment value. The value is clamped to lie between
 153 <literal>adjustment-&gt;lower</literal> and
 154 <literal>adjustment-&gt;upper</literal>.
 155 </para>
 156 <para>
 157 Note that for adjustments which are used in a #GtkScrollbar, the effective
 158 range of allowed values goes from <literal>adjustment-&gt;lower</literal> to
 159 <literal>adjustment-&gt;upper - adjustment-&gt;page_size</literal>.
 160 </para>
 161
 162 @adjustment: a #GtkAdjustment.
 163 @value: the new value.
 164
 165
 166 <!-- ##### FUNCTION gtk_adjustment_clamp_page ##### -->
 167 <para>
 168 Updates the #GtkAdjustment @value to ensure that the range between @lower
 169 and @upper is in the current page (i.e. between @value and @value +
 170 @page_size).
 171 If the range is larger than the page size, then only the start of it will
 172 be in the current page.
 173 A &quot;changed&quot; signal will be emitted if the value is changed.
 174 </para>
 175
 176 @adjustment: a #GtkAdjustment.
 177 @lower: the lower value.
 178 @upper: the upper value.
 179
 180
 181 <!-- ##### FUNCTION gtk_adjustment_changed ##### -->
 182 <para>
 183 Emits a &quot;changed&quot; signal from the #GtkAdjustment.
 184 This is typically called by the owner of the #GtkAdjustment after it has
 185 changed any of the #GtkAdjustment fields other than the value.
 186 </para>
 187
 188 @adjustment:
 189
 190
 191 <!-- ##### FUNCTION gtk_adjustment_value_changed ##### -->
 192 <para>
 193 Emits a &quot;value_changed&quot; signal from the #GtkAdjustment.
 194 This is typically called by the owner of the #GtkAdjustment after it has
 195 changed the #GtkAdjustment value field.
 196 </para>
 197
 198 @adjustment:
 199
 200