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

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