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 #GtkSpinButton widgets are created with a call to gtk_spin_button_new().
  16 </para>
  17 <para>
  18 The #GtkAdjustment of a spin button can be set or retrieved with a call to gtk_spin_button_set_adjustment() or gtk_spin_button_get_adjustment(), respectively.
  19 </para>
  20 <para>
  21 The number of digits after the decimal point of a spin button can be altered with gtk_spin_button_set_digits().
  22 </para>
  23 <para>
  24 To retrieve values from a spin button, use gtk_spin_button_get_value_as_float() if you require a floating point number, or gtk_spin_button_get_value_as_int() if you require an integer.
  25 </para>
  26 <para>
  27 To set the value of a #GtkSpinButton, use gtk_spin_button_set_value(). To change the update behaviour of a spin button, use gtk_spin_button_set_update_policy().
  28 </para>
  29 <para>
  30 When a spin button reaches it's upper or lower limit, it can either stop spinning, or wrap around and continue spinning from the opposite limit. For example, if five is the upper limit and the lower limit is zero, upon reaching the value five, the spin button can change it's value back to zero and continue spinning upwards.
  31 This behaviour is set with gtk_spin_button_set_wrap().
  32 </para>
  33 <para>
  34 A border around a spin button's arrows can be created using gtk_spin_button_set_shadow_type().
  35 </para>
  36 <para>
  37 A number may be entered that is invalid, given a spin button's range. An erroneous number can be corrected as soon as the spin button is 'activated' using gtk_spin_button_snap_to_ticks(), which will alter the current value to the nearest step increment. (See #GtkAdjustment for step increments).
  38 </para>
  39 <para>
  40 Because a spin contains a #GtkEntry, alphabetic characters may be entered. These can be ignored by using gtk_spin_button_set_numeric() with a value of TRUE. Then only numeric values, '-' and a decimal point will be accepted.
  41 </para>
  42 <para>
  43 To manually increment or decrement the spin button, use gtk_spin_button_spin(), and to force an update (refresh), use gtk_spin_button_update().
  44 </para>
  45 <para>
  46 <example>
  47 <title>Using a GtkSpinButton to get an integer.</title>
  48 <programlisting>
  49
  50 /* Provides a function to retrieve an integer value from a GtkSpinButton
  51  * and creates a spin button to model percentage values.
  52  */
  53
  54 gint grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
  55    return gtk_spin_button_get_value_as_int (a_spinner);
  56 }
  57
  58 void create_integer_spin_button(void) {
  59
  60    GtkWidget *window, *spinner;
  61    GtkAdjustment *spinner_adj;
  62
  63    spinner_adj = (GtkAdjustment *) gtk_adjustment_new(50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
  64
  65    window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
  66    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
  67
  68    /* creates the spinner, with no decimal places */
  69    spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
  70    gtk_container_add (GTK_CONTAINER(window), spinner);
  71
  72    gtk_widget_show_all (window);
  73    return;
  74 }
  75
  76 </programlisting>
  77 </example>
  78 </para>
  79
  80 <para>
  81 <example>
  82 <title>Using a GtkSpinButton to get a floating point value.</title>
  83 <programlisting>
  84
  85 /* Provides a function to retrieve a floating point value from a
  86  * GtkSpinButton, and creates a high precision spin button.
  87  */
  88
  89 gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
  90    return gtk_spin_button_get_value_as_float (a_spinner);
  91 }
  92
  93 void create_floating_spin_button(void) {
  94
  95    GtkWidget *window, *spinner;
  96    GtkAdjustment *spinner_adj;
  97
  98    spinner_adj = (GtkAdjustment *) gtk_adjustment_new(2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
  99
 100    window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
 101    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
 102
 103    /* creates the spinner, with three decimal places */
 104    spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
 105    gtk_container_add (GTK_CONTAINER(window), spinner);
 106
 107    gtk_widget_show_all (window);
 108    return;
 109 }
 110
 111 </programlisting>
 112 </example>
 113 </para>
 114
 115 <!-- ##### SECTION See_Also ##### -->
 116 <para>
 117 <variablelist>
 118 <varlistentry>
 119 <term>#GtkEntry</term>
 120 <listitem><para>retrieve text rather than numbers.</para></listitem>
 121 </varlistentry>
 122 </variablelist>
 123 </para>
 124
 125 <!-- ##### STRUCT GtkSpinButton ##### -->
 126 <para>
 127 <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.
 128 </para>
 129
 130
 131 <!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
 132 <para>
 133
 134 <informaltable pgwide=1 frame="none" role="enum">
 135 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
 136 <tbody>
 137 <row>
 138 <entry>GTK_UPDATE_ALWAYS</entry>
 139 <entry>When refreshing your #GtkSpinButton, the value is always displayed.</entry>
 140 </row>
 141 <row>
 142 <entry>GTK_UPDATE_IF_VALID</entry>
 143 <entry>When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's #GtkAdjustment.</entry>
 144 </row>
 145 </tbody></tgroup></informaltable>
 146 </para>
 147
 148 @GTK_UPDATE_ALWAYS:
 149 @GTK_UPDATE_IF_VALID:
 150
 151 <!-- ##### ENUM GtkSpinType ##### -->
 152 <para>
 153
 154 <informaltable pgwide=1 frame="none" role="struct">
 155 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
 156 <tbody>
 157 <row>
 158 <entry>GTK_SPIN_STEP_FORWARD,
 159 GTK_SPIN_STEP_BACKWARD,
 160 GTK_SPIN_PAGE_FORWARD,
 161 GTK_SPIN_PAGE_BACKWARD</entry>
 162 <entry>These values spin a #GtkSpinButton by the relevant values of the spin button's #GtkAdjustment.</entry>
 163 </row>
 164 <row>
 165 <entry>GTK_SPIN_HOME,
 166 GTK_SPIN_END</entry>
 167 <entry>These set the spin button's value to the minimum or maxmimum possible values, (set by it's #GtkAdjustment), respectively.</entry>
 168 </row>
 169 <row>
 170 <entry>GTK_SPIN_USER_DEFINED</entry>
 171 <entry>The programmer must specify the exact amount to spin the #GtkSpinButton.</entry>
 172 </row>
 173 </tbody></tgroup></informaltable>
 174 </para>
 175
 176 @GTK_SPIN_STEP_FORWARD:
 177 @GTK_SPIN_STEP_BACKWARD:
 178 @GTK_SPIN_PAGE_FORWARD:
 179 @GTK_SPIN_PAGE_BACKWARD:
 180 @GTK_SPIN_HOME:
 181 @GTK_SPIN_END:
 182 @GTK_SPIN_USER_DEFINED:
 183
 184 <!-- ##### FUNCTION gtk_spin_button_configure ##### -->
 185 <para>
 186 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.
 187 </para>
 188
 189 @spin_button: a #GtkSpinButton.
 190 @adjustment: a #GtkAdjustment.
 191 @climb_rate: the new climb rate.
 192 @digits: the number of decimal places to display in the spin button.
 193
 194
 195 <!-- ##### FUNCTION gtk_spin_button_new ##### -->
 196 <para>
 197 Creates a new #GtkSpinButton.
 198 </para>
 199
 200 @adjustment: the #GtkAdjustment object that this spin button should use.
 201 @climb_rate: specifies how much the spin button changes when an arrow is clicked on.
 202 @digits: the number of decimal places to display.
 203 @Returns: a #GtkWidget.
 204
 205
 206 <!-- ##### FUNCTION gtk_spin_button_set_adjustment ##### -->
 207 <para>
 208 Changes which #GtkAdjustment is associated with a spin button.
 209 </para>
 210
 211 @spin_button: a #GtkSpinButton.
 212 @adjustment: a #GtkAdjustment.
 213
 214
 215 <!-- ##### FUNCTION gtk_spin_button_get_adjustment ##### -->
 216 <para>
 217 Retrieves the #GtkAdjustment used by a given spin button.
 218 </para>
 219
 220 @spin_button: a #GtkSpinButton.
 221 @Returns: a #GtkAdjustment.
 222
 223
 224 <!-- ##### FUNCTION gtk_spin_button_set_digits ##### -->
 225 <para>
 226 Alters the number of decimal places that are displayed in a spin button.
 227 </para>
 228
 229 @spin_button: a #GtkSpinButton.
 230 @digits: the number of decimal places.
 231
 232
 233 <!-- ##### FUNCTION gtk_spin_button_get_value_as_float ##### -->
 234 <para>
 235 Retrieves the current value of a #GtkSpinButton. If the number has no decimal places, it is converted to a float before the function returns.
 236 </para>
 237
 238 @spin_button: a #GtkSpinButton.
 239 @Returns: the value of @spin_button as a #gfloat.
 240
 241
 242 <!-- ##### FUNCTION gtk_spin_button_get_value_as_int ##### -->
 243 <para>
 244 Retrieves the current integer value of a #GtkSpinButton.
 245 </para>
 246
 247 @spin_button: a #GtkSpinButton.
 248 @Returns: the value of @spin_button as a #gint.
 249
 250
 251 <!-- ##### FUNCTION gtk_spin_button_set_value ##### -->
 252 <para>
 253 Sets the value of a spin button.
 254 </para>
 255
 256 @spin_button: a #GtkSpinButton.
 257 @value: the new floating point value.
 258
 259
 260 <!-- ##### FUNCTION gtk_spin_button_set_update_policy ##### -->
 261 <para>
 262 Changes the way a spin button refreshes and updates itself. See %GtkSpinButtonUpdatePolicy for more information.
 263 </para>
 264
 265 @spin_button: a #GtkSpinButton.
 266 @policy: the new update policy.
 267
 268
 269 <!-- ##### FUNCTION gtk_spin_button_set_numeric ##### -->
 270 <para>
 271 Sets how the spin button's #GtkEntry reacts to alphabetic characters. A value of TRUE to @numeric means that all non-numeric characters (except '-' and a decimal point) are ignored.
 272 </para>
 273
 274 @spin_button: a #GtkSpinButton.
 275 @numeric: whether letters should be ignored.
 276
 277
 278 <!-- ##### FUNCTION gtk_spin_button_spin ##### -->
 279 <para>
 280 Performs an explicit 'spin' on a spin button.
 281 </para>
 282
 283 @spin_button: a #GtkSpinButton.
 284 @direction: the type of spin to perform.
 285 @increment: the amount to spin.
 286
 287
 288 <!-- ##### FUNCTION gtk_spin_button_set_wrap ##### -->
 289 <para>
 290 Sets a spin button's value to the lower limit when it's upper limit is reached, and vice versa.
 291 </para>
 292
 293 @spin_button: a #GtkSpinButton.
 294 @wrap: defaults to FALSE, set to TRUE to make the spin button wrap.
 295
 296
 297 <!-- ##### FUNCTION gtk_spin_button_set_shadow_type ##### -->
 298 <para>
 299 Creates a border around the arrows of a #GtkSpinButton. The type of border is determined by @shadow_type.
 300 </para>
 301
 302 @spin_button: a #GtkSpinButton
 303 @shadow_type: the new border type.
 304
 305
 306 <!-- ##### FUNCTION gtk_spin_button_set_snap_to_ticks ##### -->
 307 <para>
 308 Sets whether a number typed into a spin button should be snapped to the nearest step increment.
 309 </para>
 310
 311 @spin_button: a #GtkButton.
 312 @snap_to_ticks: TRUE or FALSE.
 313
 314
 315 <!-- ##### FUNCTION gtk_spin_button_update ##### -->
 316 <para>
 317 Refreshes a spin button. The behaviour of the update is determined by gtk_spin_button_set_update_policy().
 318 </para>
 319
 320 @spin_button: a #GtkSpinButton.
 321
 322
 323 <!-- ##### MACRO GTK_INPUT_ERROR ##### -->
 324 <para>
 325
 326 </para>
 327
 328
 329
 330 <!-- ##### SIGNAL GtkSpinButton::input ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @spinbutton: the object which received the signal.
 336 @arg1:
 337 @Returns:
 338
 339 <!-- ##### SIGNAL GtkSpinButton::output ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @spinbutton: the object which received the signal.
 345 @Returns:
 346
 347 <!-- ##### ARG GtkSpinButton:adjustment ##### -->
 348 <para>
 349 the #GtkAdjustment that defines a spin button's main properties.
 350 </para>
 351
 352 <!-- ##### ARG GtkSpinButton:climb_rate ##### -->
 353 <para>
 354 the amount a spin button changes when an arrow is clicked.
 355 </para>
 356
 357 <!-- ##### ARG GtkSpinButton:digits ##### -->
 358 <para>
 359 the number of decimal places to display.
 360 </para>
 361
 362 <!-- ##### ARG GtkSpinButton:snap_to_ticks ##### -->
 363 <para>
 364 whether erroneous values are automatically changed to a spin button's nearest step increment.
 365 </para>
 366
 367 <!-- ##### ARG GtkSpinButton:numeric ##### -->
 368 <para>
 369 whether non-numeric characters should be ignored.
 370 </para>
 371
 372 <!-- ##### ARG GtkSpinButton:wrap ##### -->
 373 <para>
 374 whether a spin button should wrap upon reaching its limits.
 375 </para>
 376
 377 <!-- ##### ARG GtkSpinButton:update_policy ##### -->
 378 <para>
 379 how a spin button should be updated.
 380 </para>
 381
 382 <!-- ##### ARG GtkSpinButton:shadow_type ##### -->
 383 <para>
 384 the type of border that surrounds the arrows of a spin button.
 385 </para>
 386
 387 <!-- ##### ARG GtkSpinButton:value ##### -->
 388 <para>
 389 reads the current value, or sets a new value.
 390 </para>
 391