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 <!-- ##### SECTION Stability_Level ##### -->
  32
  33
  34 <!-- ##### STRUCT GtkAdjustment ##### -->
  35 <para>
  36 The #GtkAdjustment-struct struct contains the following fields.
  37
  38 <informaltable pgwide="1" frame="none" role="struct">
  39 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
  40 <tbody>
  41
  42 <row>
  43 <entry>#gdouble lower;</entry>
  44 <entry>the minimum value.</entry>
  45 </row>
  46
  47 <row>
  48 <entry>#gdouble upper;</entry>
  49 <entry>the maximum value.</entry>
  50 </row>
  51
  52 <row>
  53 <entry>#gdouble value;</entry>
  54 <entry>the current value.</entry>
  55 </row>
  56
  57 <row>
  58 <entry>#gdouble step_increment;</entry>
  59 <entry>the increment to use to make minor changes to the value.
  60 In a #GtkScrollbar this increment is used when the mouse is clicked on the
  61 arrows at the top and bottom of the scrollbar, to scroll by a small amount.
  62 </entry>
  63 </row>
  64
  65 <row>
  66 <entry>#gdouble page_increment;</entry>
  67 <entry>the increment to use to make major changes to the value.
  68 In a #GtkScrollbar this increment is used when the mouse is clicked in the
  69 trough, to scroll by a large amount.
  70 </entry>
  71 </row>
  72
  73 <row>
  74 <entry>#gdouble page_size;</entry>
  75 <entry>the page size.
  76 In a #GtkScrollbar this is the size of the area which is currently visible.
  77 </entry>
  78 </row>
  79
  80 </tbody></tgroup></informaltable>
  81
  82 </para>
  83
  84
  85 <!-- ##### SIGNAL GtkAdjustment::changed ##### -->
  86 <para>
  87 Emitted when one or more of the #GtkAdjustment fields have been changed,
  88 other than the value field.
  89 </para>
  90
  91 @adjustment: the object which received the signal.
  92
  93 <!-- ##### SIGNAL GtkAdjustment::value-changed ##### -->
  94 <para>
  95 Emitted when the #GtkAdjustment value field has been changed.
  96 </para>
  97
  98 @adjustment: the object which received the signal.
  99
 100 <!-- ##### ARG GtkAdjustment:lower ##### -->
 101 <para>
 102
 103 </para>
 104
 105 <!-- ##### ARG GtkAdjustment:page-increment ##### -->
 106 <para>
 107
 108 </para>
 109
 110 <!-- ##### ARG GtkAdjustment:page-size ##### -->
 111 <para>
 112
 113 </para>
 114
 115 <!-- ##### ARG GtkAdjustment:step-increment ##### -->
 116 <para>
 117
 118 </para>
 119
 120 <!-- ##### ARG GtkAdjustment:upper ##### -->
 121 <para>
 122
 123 </para>
 124
 125 <!-- ##### ARG GtkAdjustment:value ##### -->
 126 <para>
 127
 128 </para>
 129
 130 <!-- ##### FUNCTION gtk_adjustment_new ##### -->
 131 <para>
 132 Creates a new #GtkAdjustment.
 133 </para>
 134
 135 @value: the initial value.
 136 @lower: the minimum value.
 137 @upper: the maximum value.
 138 @step_increment: the step increment.
 139 @page_increment: the page increment.
 140 @page_size: the page size.
 141 @Returns: a new #GtkAdjustment.
 142
 143
 144 <!-- ##### FUNCTION gtk_adjustment_get_value ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @adjustment:
 150 @Returns:
 151
 152
 153 <!-- ##### FUNCTION gtk_adjustment_set_value ##### -->
 154 <para>
 155 Sets the #GtkAdjustment value. The value is clamped to lie between
 156 <literal>adjustment-&gt;lower</literal> and
 157 <literal>adjustment-&gt;upper</literal>.
 158 </para>
 159 <para>
 160 Note that for adjustments which are used in a #GtkScrollbar, the effective
 161 range of allowed values goes from <literal>adjustment-&gt;lower</literal> to
 162 <literal>adjustment-&gt;upper - adjustment-&gt;page_size</literal>.
 163 </para>
 164
 165 @adjustment: a #GtkAdjustment.
 166 @value: the new value.
 167
 168
 169 <!-- ##### FUNCTION gtk_adjustment_clamp_page ##### -->
 170 <para>
 171 Updates the #GtkAdjustment @value to ensure that the range between @lower
 172 and @upper is in the current page (i.e. between @value and @value +
 173 @page_size).
 174 If the range is larger than the page size, then only the start of it will
 175 be in the current page.
 176 A &quot;changed&quot; signal will be emitted if the value is changed.
 177 </para>
 178
 179 @adjustment: a #GtkAdjustment.
 180 @lower: the lower value.
 181 @upper: the upper value.
 182
 183
 184 <!-- ##### FUNCTION gtk_adjustment_changed ##### -->
 185 <para>
 186 Emits a &quot;changed&quot; signal from the #GtkAdjustment.
 187 This is typically called by the owner of the #GtkAdjustment after it has
 188 changed any of the #GtkAdjustment fields other than the value.
 189 </para>
 190
 191 @adjustment: a #GtkAdjustment
 192
 193
 194 <!-- ##### FUNCTION gtk_adjustment_value_changed ##### -->
 195 <para>
 196 Emits a &quot;value_changed&quot; signal from the #GtkAdjustment.
 197 This is typically called by the owner of the #GtkAdjustment after it has
 198 changed the #GtkAdjustment value field.
 199 </para>
 200
 201 @adjustment: a #GtkAdjustment
 202
 203
 204 <!-- ##### FUNCTION gtk_adjustment_configure ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @adjustment:
 210 @value:
 211 @lower:
 212 @upper:
 213 @step_increment:
 214 @page_increment:
 215 @page_size:
 216
 217
 218 <!-- ##### FUNCTION gtk_adjustment_get_lower ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @adjustment:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION gtk_adjustment_get_page_increment ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @adjustment:
 233 @Returns:
 234
 235
 236 <!-- ##### FUNCTION gtk_adjustment_get_page_size ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @adjustment:
 242 @Returns:
 243
 244
 245 <!-- ##### FUNCTION gtk_adjustment_get_step_increment ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @adjustment:
 251 @Returns:
 252
 253
 254 <!-- ##### FUNCTION gtk_adjustment_get_upper ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @adjustment:
 260 @Returns:
 261
 262
 263 <!-- ##### FUNCTION gtk_adjustment_set_lower ##### -->
 264 <para>
 265
 266 </para>
 267
 268 @adjustment:
 269 @lower:
 270
 271
 272 <!-- ##### FUNCTION gtk_adjustment_set_page_increment ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @adjustment:
 278 @page_increment:
 279
 280
 281 <!-- ##### FUNCTION gtk_adjustment_set_page_size ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @adjustment:
 287 @page_size:
 288
 289
 290 <!-- ##### FUNCTION gtk_adjustment_set_step_increment ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @adjustment:
 296 @step_increment:
 297
 298
 299 <!-- ##### FUNCTION gtk_adjustment_set_upper ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @adjustment:
 305 @upper:
 306
 307