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