1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.SpinButton; 26 27 private import glib.ConstructionException; 28 private import gobject.ObjectG; 29 private import gobject.Signals; 30 private import gtk.Adjustment; 31 private import gtk.CellEditableIF; 32 private import gtk.CellEditableT; 33 private import gtk.EditableIF; 34 private import gtk.EditableT; 35 private import gtk.OrientableIF; 36 private import gtk.OrientableT; 37 private import gtk.Widget; 38 private import gtk.c.functions; 39 public import gtk.c.types; 40 private import std.algorithm; 41 42 43 /** 44 * A `GtkSpinButton` is an ideal way to allow the user to set the 45 * value of some attribute. 46 * 47 * ![An example GtkSpinButton](spinbutton.png) 48 * 49 * Rather than having to directly type a number into a `GtkEntry`, 50 * `GtkSpinButton` allows the user to click on one of two arrows 51 * to increment or decrement the displayed value. A value can still be 52 * typed in, with the bonus that it can be checked to ensure it is in a 53 * given range. 54 * 55 * The main properties of a `GtkSpinButton` are through an adjustment. 56 * See the [class@Gtk.Adjustment] documentation for more details about 57 * an adjustment's properties. 58 * 59 * Note that `GtkSpinButton` will by default make its entry large enough 60 * to accommodate the lower and upper bounds of the adjustment. If this 61 * is not desired, the automatic sizing can be turned off by explicitly 62 * setting [property@Gtk.Editable:width-chars] to a value != -1. 63 * 64 * ## Using a GtkSpinButton to get an integer 65 * 66 * ```c 67 * // Provides a function to retrieve an integer value from a GtkSpinButton 68 * // and creates a spin button to model percentage values. 69 * 70 * int 71 * grab_int_value (GtkSpinButton *button, 72 * gpointer user_data) 73 * { 74 * return gtk_spin_button_get_value_as_int (button); 75 * } 76 * 77 * void 78 * create_integer_spin_button (void) 79 * { 80 * 81 * GtkWidget *window, *button; 82 * GtkAdjustment *adjustment; 83 * 84 * adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0); 85 * 86 * window = gtk_window_new (); 87 * 88 * // creates the spinbutton, with no decimal places 89 * button = gtk_spin_button_new (adjustment, 1.0, 0); 90 * gtk_window_set_child (GTK_WINDOW (window), button); 91 * 92 * gtk_widget_show (window); 93 * } 94 * ``` 95 * 96 * ## Using a GtkSpinButton to get a floating point value 97 * 98 * ```c 99 * // Provides a function to retrieve a floating point value from a 100 * // GtkSpinButton, and creates a high precision spin button. 101 * 102 * float 103 * grab_float_value (GtkSpinButton *button, 104 * gpointer user_data) 105 * { 106 * return gtk_spin_button_get_value (button); 107 * } 108 * 109 * void 110 * create_floating_spin_button (void) 111 * { 112 * GtkWidget *window, *button; 113 * GtkAdjustment *adjustment; 114 * 115 * adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0); 116 * 117 * window = gtk_window_new (); 118 * 119 * // creates the spinbutton, with three decimal places 120 * button = gtk_spin_button_new (adjustment, 0.001, 3); 121 * gtk_window_set_child (GTK_WINDOW (window), button); 122 * 123 * gtk_widget_show (window); 124 * } 125 * ``` 126 * 127 * # CSS nodes 128 * 129 * ``` 130 * spinbutton.horizontal 131 * ├── text 132 * │ ├── undershoot.left 133 * │ ╰── undershoot.right 134 * ├── button.down 135 * ╰── button.up 136 * ``` 137 * 138 * ``` 139 * spinbutton.vertical 140 * ├── button.up 141 * ├── text 142 * │ ├── undershoot.left 143 * │ ╰── undershoot.right 144 * ╰── button.down 145 * ``` 146 * 147 * `GtkSpinButton`s main CSS node has the name spinbutton. It creates subnodes 148 * for the entry and the two buttons, with these names. The button nodes have 149 * the style classes .up and .down. The `GtkText` subnodes (if present) are put 150 * below the text node. The orientation of the spin button is reflected in 151 * the .vertical or .horizontal style class on the main node. 152 * 153 * # Accessiblity 154 * 155 * `GtkSpinButton` uses the %GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role. 156 */ 157 public class SpinButton : Widget, CellEditableIF, EditableIF, OrientableIF 158 { 159 /** the main Gtk struct */ 160 protected GtkSpinButton* gtkSpinButton; 161 162 /** Get the main Gtk struct */ 163 public GtkSpinButton* getSpinButtonStruct(bool transferOwnership = false) 164 { 165 if (transferOwnership) 166 ownedRef = false; 167 return gtkSpinButton; 168 } 169 170 /** the main Gtk struct as a void* */ 171 protected override void* getStruct() 172 { 173 return cast(void*)gtkSpinButton; 174 } 175 176 /** 177 * Sets our main struct and passes it to the parent class. 178 */ 179 public this (GtkSpinButton* gtkSpinButton, bool ownedRef = false) 180 { 181 this.gtkSpinButton = gtkSpinButton; 182 super(cast(GtkWidget*)gtkSpinButton, ownedRef); 183 } 184 185 // add the CellEditable capabilities 186 mixin CellEditableT!(GtkSpinButton); 187 188 // add the Editable capabilities 189 mixin EditableT!(GtkSpinButton); 190 191 // add the Orientable capabilities 192 mixin OrientableT!(GtkSpinButton); 193 194 195 /** */ 196 public static GType getType() 197 { 198 return gtk_spin_button_get_type(); 199 } 200 201 /** 202 * Creates a new `GtkSpinButton`. 203 * 204 * Params: 205 * adjustment = the `GtkAdjustment` that this spin 206 * button should use, or %NULL 207 * climbRate = specifies by how much the rate of change in the value will 208 * accelerate if you continue to hold down an up/down button or arrow key 209 * digits = the number of decimal places to display 210 * 211 * Returns: The new `GtkSpinButton` 212 * 213 * Throws: ConstructionException GTK+ fails to create the object. 214 */ 215 public this(Adjustment adjustment, double climbRate, uint digits) 216 { 217 auto __p = gtk_spin_button_new((adjustment is null) ? null : adjustment.getAdjustmentStruct(), climbRate, digits); 218 219 if(__p is null) 220 { 221 throw new ConstructionException("null returned by new"); 222 } 223 224 this(cast(GtkSpinButton*) __p); 225 } 226 227 /** 228 * Creates a new `GtkSpinButton` with the given properties. 229 * 230 * This is a convenience constructor that allows creation 231 * of a numeric `GtkSpinButton` without manually creating 232 * an adjustment. The value is initially set to the minimum 233 * value and a page increment of 10 * @step is the default. 234 * The precision of the spin button is equivalent to the 235 * precision of @step. 236 * 237 * Note that the way in which the precision is derived works 238 * best if @step is a power of ten. If the resulting precision 239 * is not suitable for your needs, use 240 * [method@Gtk.SpinButton.set_digits] to correct it. 241 * 242 * Params: 243 * min = Minimum allowable value 244 * max = Maximum allowable value 245 * step = Increment added or subtracted by spinning the widget 246 * 247 * Returns: The new `GtkSpinButton` 248 * 249 * Throws: ConstructionException GTK+ fails to create the object. 250 */ 251 public this(double min, double max, double step) 252 { 253 auto __p = gtk_spin_button_new_with_range(min, max, step); 254 255 if(__p is null) 256 { 257 throw new ConstructionException("null returned by new_with_range"); 258 } 259 260 this(cast(GtkSpinButton*) __p); 261 } 262 263 /** 264 * Changes the properties of an existing spin button. 265 * 266 * The adjustment, climb rate, and number of decimal places 267 * are updated accordingly. 268 * 269 * Params: 270 * adjustment = a `GtkAdjustment` to replace the spin button’s 271 * existing adjustment, or %NULL to leave its current adjustment unchanged 272 * climbRate = the new climb rate 273 * digits = the number of decimal places to display in the spin button 274 */ 275 public void configure(Adjustment adjustment, double climbRate, uint digits) 276 { 277 gtk_spin_button_configure(gtkSpinButton, (adjustment is null) ? null : adjustment.getAdjustmentStruct(), climbRate, digits); 278 } 279 280 /** 281 * Get the adjustment associated with a `GtkSpinButton`. 282 * 283 * Returns: the `GtkAdjustment` of @spin_button 284 */ 285 public Adjustment getAdjustment() 286 { 287 auto __p = gtk_spin_button_get_adjustment(gtkSpinButton); 288 289 if(__p is null) 290 { 291 return null; 292 } 293 294 return ObjectG.getDObject!(Adjustment)(cast(GtkAdjustment*) __p); 295 } 296 297 /** 298 * Returns the acceleration rate for repeated changes. 299 * 300 * Returns: the acceleration rate 301 */ 302 public double getClimbRate() 303 { 304 return gtk_spin_button_get_climb_rate(gtkSpinButton); 305 } 306 307 /** 308 * Fetches the precision of @spin_button. 309 * 310 * Returns: the current precision 311 */ 312 public uint getDigits() 313 { 314 return gtk_spin_button_get_digits(gtkSpinButton); 315 } 316 317 /** 318 * Gets the current step and page the increments 319 * used by @spin_button. 320 * 321 * See [method@Gtk.SpinButton.set_increments]. 322 * 323 * Params: 324 * step = location to store step increment, or %NULL 325 * page = location to store page increment, or %NULL 326 */ 327 public void getIncrements(out double step, out double page) 328 { 329 gtk_spin_button_get_increments(gtkSpinButton, &step, &page); 330 } 331 332 /** 333 * Returns whether non-numeric text can be typed into the spin button. 334 * 335 * Returns: %TRUE if only numeric text can be entered 336 */ 337 public bool getNumeric() 338 { 339 return gtk_spin_button_get_numeric(gtkSpinButton) != 0; 340 } 341 342 /** 343 * Gets the range allowed for @spin_button. 344 * 345 * See [method@Gtk.SpinButton.set_range]. 346 * 347 * Params: 348 * min = location to store minimum allowed value, or %NULL 349 * max = location to store maximum allowed value, or %NULL 350 */ 351 public void getRange(out double min, out double max) 352 { 353 gtk_spin_button_get_range(gtkSpinButton, &min, &max); 354 } 355 356 /** 357 * Returns whether the values are corrected to the nearest step. 358 * 359 * Returns: %TRUE if values are snapped to the nearest step 360 */ 361 public bool getSnapToTicks() 362 { 363 return gtk_spin_button_get_snap_to_ticks(gtkSpinButton) != 0; 364 } 365 366 /** 367 * Gets the update behavior of a spin button. 368 * 369 * See [method@Gtk.SpinButton.set_update_policy]. 370 * 371 * Returns: the current update policy 372 */ 373 public GtkSpinButtonUpdatePolicy getUpdatePolicy() 374 { 375 return gtk_spin_button_get_update_policy(gtkSpinButton); 376 } 377 378 /** 379 * Get the value in the @spin_button. 380 * 381 * Returns: the value of @spin_button 382 */ 383 public double getValue() 384 { 385 return gtk_spin_button_get_value(gtkSpinButton); 386 } 387 388 /** 389 * Get the value @spin_button represented as an integer. 390 * 391 * Returns: the value of @spin_button 392 */ 393 public int getValueAsInt() 394 { 395 return gtk_spin_button_get_value_as_int(gtkSpinButton); 396 } 397 398 /** 399 * Returns whether the spin button’s value wraps around to the 400 * opposite limit when the upper or lower limit of the range is 401 * exceeded. 402 * 403 * Returns: %TRUE if the spin button wraps around 404 */ 405 public bool getWrap() 406 { 407 return gtk_spin_button_get_wrap(gtkSpinButton) != 0; 408 } 409 410 /** 411 * Replaces the `GtkAdjustment` associated with @spin_button. 412 * 413 * Params: 414 * adjustment = a `GtkAdjustment` to replace the existing adjustment 415 */ 416 public void setAdjustment(Adjustment adjustment) 417 { 418 gtk_spin_button_set_adjustment(gtkSpinButton, (adjustment is null) ? null : adjustment.getAdjustmentStruct()); 419 } 420 421 /** 422 * Sets the acceleration rate for repeated changes when you 423 * hold down a button or key. 424 * 425 * Params: 426 * climbRate = the rate of acceleration, must be >= 0 427 */ 428 public void setClimbRate(double climbRate) 429 { 430 gtk_spin_button_set_climb_rate(gtkSpinButton, climbRate); 431 } 432 433 /** 434 * Set the precision to be displayed by @spin_button. 435 * 436 * Up to 20 digit precision is allowed. 437 * 438 * Params: 439 * digits = the number of digits after the decimal point to be 440 * displayed for the spin button’s value 441 */ 442 public void setDigits(uint digits) 443 { 444 gtk_spin_button_set_digits(gtkSpinButton, digits); 445 } 446 447 /** 448 * Sets the step and page increments for spin_button. 449 * 450 * This affects how quickly the value changes when 451 * the spin button’s arrows are activated. 452 * 453 * Params: 454 * step = increment applied for a button 1 press. 455 * page = increment applied for a button 2 press. 456 */ 457 public void setIncrements(double step, double page) 458 { 459 gtk_spin_button_set_increments(gtkSpinButton, step, page); 460 } 461 462 /** 463 * Sets the flag that determines if non-numeric text can be typed 464 * into the spin button. 465 * 466 * Params: 467 * numeric = flag indicating if only numeric entry is allowed 468 */ 469 public void setNumeric(bool numeric) 470 { 471 gtk_spin_button_set_numeric(gtkSpinButton, numeric); 472 } 473 474 /** 475 * Sets the minimum and maximum allowable values for @spin_button. 476 * 477 * If the current value is outside this range, it will be adjusted 478 * to fit within the range, otherwise it will remain unchanged. 479 * 480 * Params: 481 * min = minimum allowable value 482 * max = maximum allowable value 483 */ 484 public void setRange(double min, double max) 485 { 486 gtk_spin_button_set_range(gtkSpinButton, min, max); 487 } 488 489 /** 490 * Sets the policy as to whether values are corrected to the 491 * nearest step increment when a spin button is activated after 492 * providing an invalid value. 493 * 494 * Params: 495 * snapToTicks = a flag indicating if invalid values should be corrected 496 */ 497 public void setSnapToTicks(bool snapToTicks) 498 { 499 gtk_spin_button_set_snap_to_ticks(gtkSpinButton, snapToTicks); 500 } 501 502 /** 503 * Sets the update behavior of a spin button. 504 * 505 * This determines whether the spin button is always 506 * updated or only when a valid value is set. 507 * 508 * Params: 509 * policy = a `GtkSpinButtonUpdatePolicy` value 510 */ 511 public void setUpdatePolicy(GtkSpinButtonUpdatePolicy policy) 512 { 513 gtk_spin_button_set_update_policy(gtkSpinButton, policy); 514 } 515 516 /** 517 * Sets the value of @spin_button. 518 * 519 * Params: 520 * value = the new value 521 */ 522 public void setValue(double value) 523 { 524 gtk_spin_button_set_value(gtkSpinButton, value); 525 } 526 527 /** 528 * Sets the flag that determines if a spin button value wraps 529 * around to the opposite limit when the upper or lower limit 530 * of the range is exceeded. 531 * 532 * Params: 533 * wrap = a flag indicating if wrapping behavior is performed 534 */ 535 public void setWrap(bool wrap) 536 { 537 gtk_spin_button_set_wrap(gtkSpinButton, wrap); 538 } 539 540 /** 541 * Increment or decrement a spin button’s value in a specified 542 * direction by a specified amount. 543 * 544 * Params: 545 * direction = a `GtkSpinType` indicating the direction to spin 546 * increment = step increment to apply in the specified direction 547 */ 548 public void spin(GtkSpinType direction, double increment) 549 { 550 gtk_spin_button_spin(gtkSpinButton, direction, increment); 551 } 552 553 /** 554 * Manually force an update of the spin button. 555 */ 556 public void update() 557 { 558 gtk_spin_button_update(gtkSpinButton); 559 } 560 561 /** 562 * Emitted when the user initiates a value change. 563 * 564 * This is a [keybinding signal](class.SignalAction.html). 565 * 566 * Applications should not connect to it, but may emit it with 567 * g_signal_emit_by_name() if they need to control the cursor 568 * programmatically. 569 * 570 * The default bindings for this signal are Up/Down and PageUp/PageDown. 571 * 572 * Params: 573 * scroll = a #GtkScrollType to specify the speed and amount of change 574 */ 575 gulong addOnChangeValue(void delegate(GtkScrollType, SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 576 { 577 return Signals.connect(this, "change-value", dlg, connectFlags ^ ConnectFlags.SWAPPED); 578 } 579 580 /** 581 * Emitted to convert the users input into a double value. 582 * 583 * The signal handler is expected to use [method@Gtk.Editable.get_text] 584 * to retrieve the text of the spinbutton and set @new_value to the 585 * new value. 586 * 587 * The default conversion uses g_strtod(). 588 * 589 * Params: 590 * newValue = return location for the new value 591 * 592 * Returns: %TRUE for a successful conversion, %FALSE if the input 593 * was not handled, and %GTK_INPUT_ERROR if the conversion failed. 594 */ 595 gulong addOnInput(int delegate(void*, SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 596 { 597 return Signals.connect(this, "input", dlg, connectFlags ^ ConnectFlags.SWAPPED); 598 } 599 600 /** 601 * Emitted to tweak the formatting of the value for display. 602 * 603 * ```c 604 * // show leading zeros 605 * static gboolean 606 * on_output (GtkSpinButton *spin, 607 * gpointer data) 608 * { 609 * GtkAdjustment *adjustment; 610 * char *text; 611 * int value; 612 * 613 * adjustment = gtk_spin_button_get_adjustment (spin); 614 * value = (int)gtk_adjustment_get_value (adjustment); 615 * text = g_strdup_printf ("%02d", value); 616 * gtk_spin_button_set_text (spin, text): 617 * g_free (text); 618 * 619 * return TRUE; 620 * } 621 * ``` 622 * 623 * Returns: %TRUE if the value has been displayed 624 */ 625 gulong addOnOutput(bool delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 626 { 627 return Signals.connect(this, "output", dlg, connectFlags ^ ConnectFlags.SWAPPED); 628 } 629 630 /** 631 * Emitted when the value is changed. 632 * 633 * Also see the [signal@Gtk.SpinButton::output] signal. 634 */ 635 gulong addOnValueChanged(void delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 636 { 637 return Signals.connect(this, "value-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED); 638 } 639 640 /** 641 * Emitted right after the spinbutton wraps from its maximum 642 * to its minimum value or vice-versa. 643 */ 644 gulong addOnWrapped(void delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 645 { 646 return Signals.connect(this, "wrapped", dlg, connectFlags ^ ConnectFlags.SWAPPED); 647 } 648 }