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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkSpinButton
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Retrieve an integer or floating-point number from the user
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GtkSpinButton is an ideal way to allow the user to set the value of some
  10 attribute. Rather than having to directly type a number into a #GtkEntry,
  11 #GtkSpinButton allows the user to click on one of two arrows to increment or
  12 decrement the displayed value. A value can still be typed in, with the bonus
  13 that it can be checked to ensure it is in a given range.
  14 </para>
  15 <para>
  16 The main properties of a #GtkSpinButton are through a #GtkAdjustment. See the
  17 #GtkAdjustment section for more details about an adjustment's properties.
  18 </para>
  19 <para>
  20 <example>
  21 <title>Using a <structname>GtkSpinButton</structname> to get an integer.</title>
  22 <programlisting>
  23
  24 /* Provides a function to retrieve an integer value from a GtkSpinButton
  25  * and creates a spin button to model percentage values.
  26  */
  27
  28 gint grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
  29    return gtk_spin_button_get_value_as_int (a_spinner);
  30 }
  31
  32 void create_integer_spin_button (void) {
  33
  34    GtkWidget *window, *spinner;
  35    GtkAdjustment *spinner_adj;
  36
  37    spinner_adj = (GtkAdjustment *) gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
  38
  39    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  40    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
  41
  42    /* creates the spinner, with no decimal places */
  43    spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
  44    gtk_container_add (GTK_CONTAINER (window), spinner);
  45
  46    gtk_widget_show_all (window);
  47    return;
  48 }
  49
  50 </programlisting>
  51 </example>
  52 </para>
  53
  54 <para>
  55 <example>
  56 <title>Using a <structname>GtkSpinButton</structname> to get a floating point value.</title>
  57 <programlisting>
  58
  59 /* Provides a function to retrieve a floating point value from a
  60  * GtkSpinButton, and creates a high precision spin button.
  61  */
  62
  63 gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
  64    return gtk_spin_button_get_value (a_spinner);
  65 }
  66
  67 void create_floating_spin_button (void) {
  68
  69    GtkWidget *window, *spinner;
  70    GtkAdjustment *spinner_adj;
  71
  72    spinner_adj = (GtkAdjustment *) gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
  73
  74    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  75    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
  76
  77    /* creates the spinner, with three decimal places */
  78    spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
  79    gtk_container_add (GTK_CONTAINER (window), spinner);
  80
  81    gtk_widget_show_all (window);
  82    return;
  83 }
  84
  85 </programlisting>
  86 </example>
  87 </para>
  88
  89 <!-- ##### SECTION See_Also ##### -->
  90 <para>
  91 <variablelist>
  92 <varlistentry>
  93 <term>#GtkEntry</term>
  94 <listitem><para>retrieve text rather than numbers.</para></listitem>
  95 </varlistentry>
  96 </variablelist>
  97 </para>
  98
  99 <!-- ##### SECTION Stability_Level ##### -->
 100
 101
 102 <!-- ##### SECTION Image ##### -->
 103
 104
 105 <!-- ##### STRUCT GtkSpinButton ##### -->
 106 <para>
 107 <structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton
 108 widget, and can be used accordingly. All other fields contain private data
 109 and should only be modified using the functions below.
 110 </para>
 111
 112
 113 <!-- ##### SIGNAL GtkSpinButton::change-value ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @spinbutton: the object which received the signal.
 119 @arg1:
 120
 121 <!-- ##### SIGNAL GtkSpinButton::input ##### -->
 122 <para>
 123
 124 </para>
 125
 126 @spinbutton: the object which received the signal.
 127 @arg1:
 128 @Returns:
 129
 130 <!-- ##### SIGNAL GtkSpinButton::output ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @spinbutton: the object which received the signal.
 136 @Returns:
 137
 138 <!-- ##### SIGNAL GtkSpinButton::value-changed ##### -->
 139 <para>
 140
 141 </para>
 142
 143 @spinbutton: the object which received the signal.
 144
 145 <!-- ##### SIGNAL GtkSpinButton::wrapped ##### -->
 146 <para>
 147
 148 </para>
 149
 150 @spinbutton: the object which received the signal.
 151
 152 <!-- ##### ARG GtkSpinButton:adjustment ##### -->
 153 <para>
 154
 155 </para>
 156
 157 <!-- ##### ARG GtkSpinButton:climb-rate ##### -->
 158 <para>
 159
 160 </para>
 161
 162 <!-- ##### ARG GtkSpinButton:digits ##### -->
 163 <para>
 164
 165 </para>
 166
 167 <!-- ##### ARG GtkSpinButton:numeric ##### -->
 168 <para>
 169
 170 </para>
 171
 172 <!-- ##### ARG GtkSpinButton:snap-to-ticks ##### -->
 173 <para>
 174
 175 </para>
 176
 177 <!-- ##### ARG GtkSpinButton:update-policy ##### -->
 178 <para>
 179
 180 </para>
 181
 182 <!-- ##### ARG GtkSpinButton:value ##### -->
 183 <para>
 184
 185 </para>
 186
 187 <!-- ##### ARG GtkSpinButton:wrap ##### -->
 188 <para>
 189
 190 </para>
 191
 192 <!-- ##### ARG GtkSpinButton:shadow-type ##### -->
 193 <para>
 194 the type of border that surrounds the arrows of a spin button.
 195 </para>
 196
 197 <!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
 198 <para>
 199
 200 <informaltable pgwide="1" frame="none" role="enum">
 201 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
 202 <tbody>
 203 <row>
 204 <entry>GTK_UPDATE_ALWAYS</entry>
 205 <entry>When refreshing your #GtkSpinButton, the value is always displayed.</entry>
 206 </row>
 207 <row>
 208 <entry>GTK_UPDATE_IF_VALID</entry>
 209 <entry>When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's #GtkAdjustment.</entry>
 210 </row>
 211 </tbody></tgroup></informaltable>
 212 </para>
 213
 214 @GTK_UPDATE_ALWAYS:
 215 @GTK_UPDATE_IF_VALID:
 216
 217 <!-- ##### ENUM GtkSpinType ##### -->
 218 <para>
 219
 220 <informaltable pgwide="1" frame="none" role="struct">
 221 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
 222 <tbody>
 223 <row>
 224 <entry>GTK_SPIN_STEP_FORWARD,
 225 GTK_SPIN_STEP_BACKWARD,
 226 GTK_SPIN_PAGE_FORWARD,
 227 GTK_SPIN_PAGE_BACKWARD</entry>
 228 <entry>These values spin a #GtkSpinButton by the relevant values of the spin button's #GtkAdjustment.</entry>
 229 </row>
 230 <row>
 231 <entry>GTK_SPIN_HOME,
 232 GTK_SPIN_END</entry>
 233 <entry>These set the spin button's value to the minimum or maxmimum possible values, (set by its #GtkAdjustment), respectively.</entry>
 234 </row>
 235 <row>
 236 <entry>GTK_SPIN_USER_DEFINED</entry>
 237 <entry>The programmer must specify the exact amount to spin the #GtkSpinButton.</entry>
 238 </row>
 239 </tbody></tgroup></informaltable>
 240 </para>
 241
 242 @GTK_SPIN_STEP_FORWARD:
 243 @GTK_SPIN_STEP_BACKWARD:
 244 @GTK_SPIN_PAGE_FORWARD:
 245 @GTK_SPIN_PAGE_BACKWARD:
 246 @GTK_SPIN_HOME:
 247 @GTK_SPIN_END:
 248 @GTK_SPIN_USER_DEFINED:
 249
 250 <!-- ##### FUNCTION gtk_spin_button_configure ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @spin_button:
 256 @adjustment:
 257 @climb_rate:
 258 @digits:
 259
 260
 261 <!-- ##### FUNCTION gtk_spin_button_new ##### -->
 262 <para>
 263 Creates a new #GtkSpinButton.
 264 </para>
 265
 266 @adjustment: the #GtkAdjustment object that this spin button should use.
 267 @climb_rate: specifies how much the spin button changes when an arrow is clicked on.
 268 @digits: the number of decimal places to display.
 269 @Returns: The new spin button as a #GtkWidget.
 270
 271
 272 <!-- ##### FUNCTION gtk_spin_button_new_with_range ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @min:
 278 @max:
 279 @step:
 280 @Returns:
 281
 282
 283 <!-- ##### FUNCTION gtk_spin_button_set_adjustment ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @spin_button:
 289 @adjustment:
 290
 291
 292 <!-- ##### FUNCTION gtk_spin_button_get_adjustment ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @spin_button:
 298 @Returns:
 299
 300
 301 <!-- ##### FUNCTION gtk_spin_button_set_digits ##### -->
 302 <para>
 303
 304 </para>
 305
 306 @spin_button:
 307 @digits:
 308
 309
 310 <!-- ##### FUNCTION gtk_spin_button_set_increments ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @spin_button:
 316 @step:
 317 @page:
 318
 319
 320 <!-- ##### FUNCTION gtk_spin_button_set_range ##### -->
 321 <para>
 322
 323 </para>
 324
 325 @spin_button:
 326 @min:
 327 @max:
 328
 329
 330 <!-- ##### FUNCTION gtk_spin_button_get_value_as_int ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @spin_button:
 336 @Returns:
 337
 338
 339 <!-- ##### FUNCTION gtk_spin_button_set_value ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @spin_button:
 345 @value:
 346
 347
 348 <!-- ##### FUNCTION gtk_spin_button_set_update_policy ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @spin_button:
 354 @policy:
 355
 356
 357 <!-- ##### FUNCTION gtk_spin_button_set_numeric ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @spin_button:
 363 @numeric:
 364
 365
 366 <!-- ##### FUNCTION gtk_spin_button_spin ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @spin_button:
 372 @direction:
 373 @increment:
 374
 375
 376 <!-- ##### FUNCTION gtk_spin_button_set_wrap ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @spin_button:
 382 @wrap:
 383
 384
 385 <!-- ##### FUNCTION gtk_spin_button_set_snap_to_ticks ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @spin_button:
 391 @snap_to_ticks:
 392
 393
 394 <!-- ##### FUNCTION gtk_spin_button_update ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @spin_button:
 400
 401
 402 <!-- ##### FUNCTION gtk_spin_button_get_digits ##### -->
 403 <para>
 404
 405 </para>
 406
 407 @spin_button:
 408 @Returns:
 409
 410
 411 <!-- ##### FUNCTION gtk_spin_button_get_increments ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @spin_button:
 417 @step:
 418 @page:
 419
 420
 421 <!-- ##### FUNCTION gtk_spin_button_get_numeric ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @spin_button:
 427 @Returns:
 428
 429
 430 <!-- ##### FUNCTION gtk_spin_button_get_range ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @spin_button:
 436 @min:
 437 @max:
 438
 439
 440 <!-- ##### FUNCTION gtk_spin_button_get_snap_to_ticks ##### -->
 441 <para>
 442
 443 </para>
 444
 445 @spin_button:
 446 @Returns:
 447
 448
 449 <!-- ##### FUNCTION gtk_spin_button_get_update_policy ##### -->
 450 <para>
 451
 452 </para>
 453
 454 @spin_button:
 455 @Returns:
 456
 457
 458 <!-- ##### FUNCTION gtk_spin_button_get_value ##### -->
 459 <para>
 460
 461 </para>
 462
 463 @spin_button:
 464 @Returns:
 465
 466
 467 <!-- ##### FUNCTION gtk_spin_button_get_wrap ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @spin_button:
 473 @Returns:
 474
 475
 476 <!-- ##### MACRO GTK_INPUT_ERROR ##### -->
 477 <para>
 478
 479 </para>
 480
 481
 482