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