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 <!-- ##### STRUCT GtkSpinButton ##### -->
 103 <para>
 104 <structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton
 105 widget, and can be used accordingly. All other fields contain private data
 106 and should only be modified using the functions below.
 107 </para>
 108
 109
 110 <!-- ##### SIGNAL GtkSpinButton::change-value ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @spinbutton: the object which received the signal.
 116 @arg1:
 117
 118 <!-- ##### SIGNAL GtkSpinButton::input ##### -->
 119 <para>
 120
 121 </para>
 122
 123 @spinbutton: the object which received the signal.
 124 @arg1:
 125 @Returns:
 126
 127 <!-- ##### SIGNAL GtkSpinButton::output ##### -->
 128 <para>
 129
 130 </para>
 131
 132 @spinbutton: the object which received the signal.
 133 @Returns:
 134
 135 <!-- ##### SIGNAL GtkSpinButton::value-changed ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @spinbutton: the object which received the signal.
 141
 142 <!-- ##### SIGNAL GtkSpinButton::wrapped ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @spinbutton: the object which received the signal.
 148
 149 <!-- ##### ARG GtkSpinButton:adjustment ##### -->
 150 <para>
 151
 152 </para>
 153
 154 <!-- ##### ARG GtkSpinButton:climb-rate ##### -->
 155 <para>
 156
 157 </para>
 158
 159 <!-- ##### ARG GtkSpinButton:digits ##### -->
 160 <para>
 161
 162 </para>
 163
 164 <!-- ##### ARG GtkSpinButton:numeric ##### -->
 165 <para>
 166
 167 </para>
 168
 169 <!-- ##### ARG GtkSpinButton:snap-to-ticks ##### -->
 170 <para>
 171
 172 </para>
 173
 174 <!-- ##### ARG GtkSpinButton:update-policy ##### -->
 175 <para>
 176
 177 </para>
 178
 179 <!-- ##### ARG GtkSpinButton:value ##### -->
 180 <para>
 181
 182 </para>
 183
 184 <!-- ##### ARG GtkSpinButton:wrap ##### -->
 185 <para>
 186
 187 </para>
 188
 189 <!-- ##### ARG GtkSpinButton:shadow-type ##### -->
 190 <para>
 191 the type of border that surrounds the arrows of a spin button.
 192 </para>
 193
 194 <!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
 195 <para>
 196
 197 <informaltable pgwide="1" frame="none" role="enum">
 198 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
 199 <tbody>
 200 <row>
 201 <entry>GTK_UPDATE_ALWAYS</entry>
 202 <entry>When refreshing your #GtkSpinButton, the value is always displayed.</entry>
 203 </row>
 204 <row>
 205 <entry>GTK_UPDATE_IF_VALID</entry>
 206 <entry>When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's #GtkAdjustment.</entry>
 207 </row>
 208 </tbody></tgroup></informaltable>
 209 </para>
 210
 211 @GTK_UPDATE_ALWAYS:
 212 @GTK_UPDATE_IF_VALID:
 213
 214 <!-- ##### ENUM GtkSpinType ##### -->
 215 <para>
 216
 217 <informaltable pgwide="1" frame="none" role="struct">
 218 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
 219 <tbody>
 220 <row>
 221 <entry>GTK_SPIN_STEP_FORWARD,
 222 GTK_SPIN_STEP_BACKWARD,
 223 GTK_SPIN_PAGE_FORWARD,
 224 GTK_SPIN_PAGE_BACKWARD</entry>
 225 <entry>These values spin a #GtkSpinButton by the relevant values of the spin button's #GtkAdjustment.</entry>
 226 </row>
 227 <row>
 228 <entry>GTK_SPIN_HOME,
 229 GTK_SPIN_END</entry>
 230 <entry>These set the spin button's value to the minimum or maxmimum possible values, (set by its #GtkAdjustment), respectively.</entry>
 231 </row>
 232 <row>
 233 <entry>GTK_SPIN_USER_DEFINED</entry>
 234 <entry>The programmer must specify the exact amount to spin the #GtkSpinButton.</entry>
 235 </row>
 236 </tbody></tgroup></informaltable>
 237 </para>
 238
 239 @GTK_SPIN_STEP_FORWARD:
 240 @GTK_SPIN_STEP_BACKWARD:
 241 @GTK_SPIN_PAGE_FORWARD:
 242 @GTK_SPIN_PAGE_BACKWARD:
 243 @GTK_SPIN_HOME:
 244 @GTK_SPIN_END:
 245 @GTK_SPIN_USER_DEFINED:
 246
 247 <!-- ##### FUNCTION gtk_spin_button_configure ##### -->
 248 <para>
 249 Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call.
 250 </para>
 251
 252 @spin_button: a #GtkSpinButton.
 253 @adjustment: a #GtkAdjustment.
 254 @climb_rate: the new climb rate.
 255 @digits: the number of decimal places to display in the spin button.
 256
 257
 258 <!-- ##### FUNCTION gtk_spin_button_new ##### -->
 259 <para>
 260 Creates a new #GtkSpinButton.
 261 </para>
 262
 263 @adjustment: the #GtkAdjustment object that this spin button should use.
 264 @climb_rate: specifies how much the spin button changes when an arrow is clicked on.
 265 @digits: the number of decimal places to display.
 266 @Returns: The new spin button as a #GtkWidget.
 267
 268
 269 <!-- ##### FUNCTION gtk_spin_button_new_with_range ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @min:
 275 @max:
 276 @step:
 277 @Returns:
 278
 279
 280 <!-- ##### FUNCTION gtk_spin_button_set_adjustment ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @spin_button:
 286 @adjustment:
 287
 288
 289 <!-- ##### FUNCTION gtk_spin_button_get_adjustment ##### -->
 290 <para>
 291
 292 </para>
 293
 294 @spin_button:
 295 @Returns:
 296
 297
 298 <!-- ##### FUNCTION gtk_spin_button_set_digits ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @spin_button:
 304 @digits:
 305
 306
 307 <!-- ##### FUNCTION gtk_spin_button_set_increments ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @spin_button:
 313 @step:
 314 @page:
 315
 316
 317 <!-- ##### FUNCTION gtk_spin_button_set_range ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @spin_button:
 323 @min:
 324 @max:
 325
 326
 327 <!-- ##### MACRO gtk_spin_button_get_value_as_float ##### -->
 328 <para>
 329 Gets the value in the @spin_button. This function is deprecated,
 330 use gtk_spin_button_get_value() instead.
 331 </para>
 332
 333 @Returns: the value of @spin_button.
 334 <!-- # Unused Parameters # -->
 335 @spin_button: a #GtkSpinButton.
 336
 337
 338 <!-- ##### FUNCTION gtk_spin_button_get_value_as_int ##### -->
 339 <para>
 340
 341 </para>
 342
 343 @spin_button:
 344 @Returns:
 345
 346
 347 <!-- ##### FUNCTION gtk_spin_button_set_value ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @spin_button:
 353 @value:
 354
 355
 356 <!-- ##### FUNCTION gtk_spin_button_set_update_policy ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @spin_button:
 362 @policy:
 363
 364
 365 <!-- ##### FUNCTION gtk_spin_button_set_numeric ##### -->
 366 <para>
 367
 368 </para>
 369
 370 @spin_button:
 371 @numeric:
 372
 373
 374 <!-- ##### FUNCTION gtk_spin_button_spin ##### -->
 375 <para>
 376
 377 </para>
 378
 379 @spin_button:
 380 @direction:
 381 @increment:
 382
 383
 384 <!-- ##### FUNCTION gtk_spin_button_set_wrap ##### -->
 385 <para>
 386
 387 </para>
 388
 389 @spin_button:
 390 @wrap:
 391
 392
 393 <!-- ##### FUNCTION gtk_spin_button_set_snap_to_ticks ##### -->
 394 <para>
 395
 396 </para>
 397
 398 @spin_button:
 399 @snap_to_ticks:
 400
 401
 402 <!-- ##### FUNCTION gtk_spin_button_update ##### -->
 403 <para>
 404
 405 </para>
 406
 407 @spin_button:
 408
 409
 410 <!-- ##### FUNCTION gtk_spin_button_get_digits ##### -->
 411 <para>
 412
 413 </para>
 414
 415 @spin_button:
 416 @Returns:
 417
 418
 419 <!-- ##### FUNCTION gtk_spin_button_get_increments ##### -->
 420 <para>
 421
 422 </para>
 423
 424 @spin_button:
 425 @step:
 426 @page:
 427
 428
 429 <!-- ##### FUNCTION gtk_spin_button_get_numeric ##### -->
 430 <para>
 431
 432 </para>
 433
 434 @spin_button:
 435 @Returns:
 436
 437
 438 <!-- ##### FUNCTION gtk_spin_button_get_range ##### -->
 439 <para>
 440
 441 </para>
 442
 443 @spin_button:
 444 @min:
 445 @max:
 446
 447
 448 <!-- ##### FUNCTION gtk_spin_button_get_snap_to_ticks ##### -->
 449 <para>
 450
 451 </para>
 452
 453 @spin_button:
 454 @Returns:
 455
 456
 457 <!-- ##### FUNCTION gtk_spin_button_get_update_policy ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @spin_button:
 463 @Returns:
 464
 465
 466 <!-- ##### FUNCTION gtk_spin_button_get_value ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @spin_button:
 472 @Returns:
 473
 474
 475 <!-- ##### FUNCTION gtk_spin_button_get_wrap ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @spin_button:
 481 @Returns:
 482
 483
 484 <!-- ##### MACRO GTK_INPUT_ERROR ##### -->
 485 <para>
 486
 487 </para>
 488
 489
 490