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.Entry;
32 private import gtk.OrientableIF;
33 private import gtk.OrientableT;
34 private import gtk.Widget;
35 public  import gtkc.gdktypes;
36 private import gtkc.gtk;
37 public  import gtkc.gtktypes;
38 
39 
40 /**
41  * A #GtkSpinButton is an ideal way to allow the user to set the value of
42  * some attribute. Rather than having to directly type a number into a
43  * #GtkEntry, GtkSpinButton allows the user to click on one of two arrows
44  * to increment or decrement the displayed value. A value can still be
45  * typed in, with the bonus that it can be checked to ensure it is in a
46  * given range.
47  * 
48  * The main properties of a GtkSpinButton are through an adjustment.
49  * See the #GtkAdjustment section for more details about an adjustment's
50  * properties. Note that GtkSpinButton will by default make its entry
51  * large enough to accomodate the lower and upper bounds of the adjustment,
52  * which can lead to surprising results. Best practice is to set both
53  * the #GtkEntry:width-chars and #GtkEntry:max-width-chars poperties
54  * to the desired number of characters to display in the entry.
55  * 
56  * # CSS nodes
57  * 
58  * |[<!-- language="plain" -->
59  * spinbutton.horizontal
60  * ├── entry
61  * │   ╰── ...
62  * ├── button.down
63  * ╰── button.up
64  * ]|
65  * 
66  * |[<!-- language="plain" -->
67  * spinbutton.vertical
68  * ├── button.up
69  * ├── entry
70  * │   ╰── ...
71  * ╰── button.down
72  * ]|
73  * 
74  * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
75  * for the entry and the two buttons, with these names. The button nodes have
76  * the style classes .up and .down. The GtkEntry subnodes (if present) are put
77  * below the entry node. The orientation of the spin button is reflected in
78  * the .vertical or .horizontal style class on the main node.
79  * 
80  * ## Using a GtkSpinButton to get an integer
81  * 
82  * |[<!-- language="C" -->
83  * // Provides a function to retrieve an integer value from a GtkSpinButton
84  * // and creates a spin button to model percentage values.
85  * 
86  * gint
87  * grab_int_value (GtkSpinButton *button,
88  * gpointer       user_data)
89  * {
90  * return gtk_spin_button_get_value_as_int (button);
91  * }
92  * 
93  * void
94  * create_integer_spin_button (void)
95  * {
96  * 
97  * GtkWidget *window, *button;
98  * GtkAdjustment *adjustment;
99  * 
100  * adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0);
101  * 
102  * window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
103  * gtk_container_set_border_width (GTK_CONTAINER (window), 5);
104  * 
105  * // creates the spinbutton, with no decimal places
106  * button = gtk_spin_button_new (adjustment, 1.0, 0);
107  * gtk_container_add (GTK_CONTAINER (window), button);
108  * 
109  * gtk_widget_show_all (window);
110  * }
111  * ]|
112  * 
113  * ## Using a GtkSpinButton to get a floating point value
114  * 
115  * |[<!-- language="C" -->
116  * // Provides a function to retrieve a floating point value from a
117  * // GtkSpinButton, and creates a high precision spin button.
118  * 
119  * gfloat
120  * grab_float_value (GtkSpinButton *button,
121  * gpointer       user_data)
122  * {
123  * return gtk_spin_button_get_value (button);
124  * }
125  * 
126  * void
127  * create_floating_spin_button (void)
128  * {
129  * GtkWidget *window, *button;
130  * GtkAdjustment *adjustment;
131  * 
132  * adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0);
133  * 
134  * window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
135  * gtk_container_set_border_width (GTK_CONTAINER (window), 5);
136  * 
137  * // creates the spinbutton, with three decimal places
138  * button = gtk_spin_button_new (adjustment, 0.001, 3);
139  * gtk_container_add (GTK_CONTAINER (window), button);
140  * 
141  * gtk_widget_show_all (window);
142  * }
143  * ]|
144  */
145 public class SpinButton : Entry, OrientableIF
146 {
147 	/** the main Gtk struct */
148 	protected GtkSpinButton* gtkSpinButton;
149 
150 	/** Get the main Gtk struct */
151 	public GtkSpinButton* getSpinButtonStruct()
152 	{
153 		return gtkSpinButton;
154 	}
155 
156 	/** the main Gtk struct as a void* */
157 	protected override void* getStruct()
158 	{
159 		return cast(void*)gtkSpinButton;
160 	}
161 
162 	protected override void setStruct(GObject* obj)
163 	{
164 		gtkSpinButton = cast(GtkSpinButton*)obj;
165 		super.setStruct(obj);
166 	}
167 
168 	/**
169 	 * Sets our main struct and passes it to the parent class.
170 	 */
171 	public this (GtkSpinButton* gtkSpinButton, bool ownedRef = false)
172 	{
173 		this.gtkSpinButton = gtkSpinButton;
174 		super(cast(GtkEntry*)gtkSpinButton, ownedRef);
175 	}
176 
177 	// add the Orientable capabilities
178 	mixin OrientableT!(GtkSpinButton);
179 
180 
181 	/** */
182 	public static GType getType()
183 	{
184 		return gtk_spin_button_get_type();
185 	}
186 
187 	/**
188 	 * Creates a new #GtkSpinButton.
189 	 *
190 	 * Params:
191 	 *     adjustment = the #GtkAdjustment object that this spin
192 	 *         button should use, or %NULL
193 	 *     climbRate = specifies how much the spin button changes when an arrow
194 	 *         is clicked on
195 	 *     digits = the number of decimal places to display
196 	 *
197 	 * Return: The new spin button as a #GtkWidget
198 	 *
199 	 * Throws: ConstructionException GTK+ fails to create the object.
200 	 */
201 	public this(Adjustment adjustment, double climbRate, uint digits)
202 	{
203 		auto p = gtk_spin_button_new((adjustment is null) ? null : adjustment.getAdjustmentStruct(), climbRate, digits);
204 		
205 		if(p is null)
206 		{
207 			throw new ConstructionException("null returned by new");
208 		}
209 		
210 		this(cast(GtkSpinButton*) p);
211 	}
212 
213 	/**
214 	 * This is a convenience constructor that allows creation of a numeric
215 	 * #GtkSpinButton without manually creating an adjustment. The value is
216 	 * initially set to the minimum value and a page increment of 10 * @step
217 	 * is the default. The precision of the spin button is equivalent to the
218 	 * precision of @step.
219 	 *
220 	 * Note that the way in which the precision is derived works best if @step
221 	 * is a power of ten. If the resulting precision is not suitable for your
222 	 * needs, use gtk_spin_button_set_digits() to correct it.
223 	 *
224 	 * Params:
225 	 *     min = Minimum allowable value
226 	 *     max = Maximum allowable value
227 	 *     step = Increment added or subtracted by spinning the widget
228 	 *
229 	 * Return: The new spin button as a #GtkWidget
230 	 *
231 	 * Throws: ConstructionException GTK+ fails to create the object.
232 	 */
233 	public this(double min, double max, double step)
234 	{
235 		auto p = gtk_spin_button_new_with_range(min, max, step);
236 		
237 		if(p is null)
238 		{
239 			throw new ConstructionException("null returned by new_with_range");
240 		}
241 		
242 		this(cast(GtkSpinButton*) p);
243 	}
244 
245 	/**
246 	 * Changes the properties of an existing spin button. The adjustment,
247 	 * climb rate, and number of decimal places are all changed accordingly,
248 	 * after this function call.
249 	 *
250 	 * Params:
251 	 *     adjustment = a #GtkAdjustment
252 	 *     climbRate = the new climb rate
253 	 *     digits = the number of decimal places to display in the spin button
254 	 */
255 	public void configure(Adjustment adjustment, double climbRate, uint digits)
256 	{
257 		gtk_spin_button_configure(gtkSpinButton, (adjustment is null) ? null : adjustment.getAdjustmentStruct(), climbRate, digits);
258 	}
259 
260 	/**
261 	 * Get the adjustment associated with a #GtkSpinButton
262 	 *
263 	 * Return: the #GtkAdjustment of @spin_button
264 	 */
265 	public Adjustment getAdjustment()
266 	{
267 		auto p = gtk_spin_button_get_adjustment(gtkSpinButton);
268 		
269 		if(p is null)
270 		{
271 			return null;
272 		}
273 		
274 		return ObjectG.getDObject!(Adjustment)(cast(GtkAdjustment*) p);
275 	}
276 
277 	/**
278 	 * Fetches the precision of @spin_button. See gtk_spin_button_set_digits().
279 	 *
280 	 * Return: the current precision
281 	 */
282 	public uint getDigits()
283 	{
284 		return gtk_spin_button_get_digits(gtkSpinButton);
285 	}
286 
287 	/**
288 	 * Gets the current step and page the increments used by @spin_button. See
289 	 * gtk_spin_button_set_increments().
290 	 *
291 	 * Params:
292 	 *     step = location to store step increment, or %NULL
293 	 *     page = location to store page increment, or %NULL
294 	 */
295 	public void getIncrements(out double step, out double page)
296 	{
297 		gtk_spin_button_get_increments(gtkSpinButton, &step, &page);
298 	}
299 
300 	/**
301 	 * Returns whether non-numeric text can be typed into the spin button.
302 	 * See gtk_spin_button_set_numeric().
303 	 *
304 	 * Return: %TRUE if only numeric text can be entered
305 	 */
306 	public bool getNumeric()
307 	{
308 		return gtk_spin_button_get_numeric(gtkSpinButton) != 0;
309 	}
310 
311 	/**
312 	 * Gets the range allowed for @spin_button.
313 	 * See gtk_spin_button_set_range().
314 	 *
315 	 * Params:
316 	 *     min = location to store minimum allowed value, or %NULL
317 	 *     max = location to store maximum allowed value, or %NULL
318 	 */
319 	public void getRange(out double min, out double max)
320 	{
321 		gtk_spin_button_get_range(gtkSpinButton, &min, &max);
322 	}
323 
324 	/**
325 	 * Returns whether the values are corrected to the nearest step.
326 	 * See gtk_spin_button_set_snap_to_ticks().
327 	 *
328 	 * Return: %TRUE if values are snapped to the nearest step
329 	 */
330 	public bool getSnapToTicks()
331 	{
332 		return gtk_spin_button_get_snap_to_ticks(gtkSpinButton) != 0;
333 	}
334 
335 	/**
336 	 * Gets the update behavior of a spin button.
337 	 * See gtk_spin_button_set_update_policy().
338 	 *
339 	 * Return: the current update policy
340 	 */
341 	public GtkSpinButtonUpdatePolicy getUpdatePolicy()
342 	{
343 		return gtk_spin_button_get_update_policy(gtkSpinButton);
344 	}
345 
346 	/**
347 	 * Get the value in the @spin_button.
348 	 *
349 	 * Return: the value of @spin_button
350 	 */
351 	public double getValue()
352 	{
353 		return gtk_spin_button_get_value(gtkSpinButton);
354 	}
355 
356 	/**
357 	 * Get the value @spin_button represented as an integer.
358 	 *
359 	 * Return: the value of @spin_button
360 	 */
361 	public int getValueAsInt()
362 	{
363 		return gtk_spin_button_get_value_as_int(gtkSpinButton);
364 	}
365 
366 	/**
367 	 * Returns whether the spin button’s value wraps around to the
368 	 * opposite limit when the upper or lower limit of the range is
369 	 * exceeded. See gtk_spin_button_set_wrap().
370 	 *
371 	 * Return: %TRUE if the spin button wraps around
372 	 */
373 	public bool getWrap()
374 	{
375 		return gtk_spin_button_get_wrap(gtkSpinButton) != 0;
376 	}
377 
378 	/**
379 	 * Replaces the #GtkAdjustment associated with @spin_button.
380 	 *
381 	 * Params:
382 	 *     adjustment = a #GtkAdjustment to replace the existing adjustment
383 	 */
384 	public void setAdjustment(Adjustment adjustment)
385 	{
386 		gtk_spin_button_set_adjustment(gtkSpinButton, (adjustment is null) ? null : adjustment.getAdjustmentStruct());
387 	}
388 
389 	/**
390 	 * Set the precision to be displayed by @spin_button. Up to 20 digit precision
391 	 * is allowed.
392 	 *
393 	 * Params:
394 	 *     digits = the number of digits after the decimal point to be displayed for the spin button’s value
395 	 */
396 	public void setDigits(uint digits)
397 	{
398 		gtk_spin_button_set_digits(gtkSpinButton, digits);
399 	}
400 
401 	/**
402 	 * Sets the step and page increments for spin_button.  This affects how
403 	 * quickly the value changes when the spin button’s arrows are activated.
404 	 *
405 	 * Params:
406 	 *     step = increment applied for a button 1 press.
407 	 *     page = increment applied for a button 2 press.
408 	 */
409 	public void setIncrements(double step, double page)
410 	{
411 		gtk_spin_button_set_increments(gtkSpinButton, step, page);
412 	}
413 
414 	/**
415 	 * Sets the flag that determines if non-numeric text can be typed
416 	 * into the spin button.
417 	 *
418 	 * Params:
419 	 *     numeric = flag indicating if only numeric entry is allowed
420 	 */
421 	public void setNumeric(bool numeric)
422 	{
423 		gtk_spin_button_set_numeric(gtkSpinButton, numeric);
424 	}
425 
426 	/**
427 	 * Sets the minimum and maximum allowable values for @spin_button.
428 	 *
429 	 * If the current value is outside this range, it will be adjusted
430 	 * to fit within the range, otherwise it will remain unchanged.
431 	 *
432 	 * Params:
433 	 *     min = minimum allowable value
434 	 *     max = maximum allowable value
435 	 */
436 	public void setRange(double min, double max)
437 	{
438 		gtk_spin_button_set_range(gtkSpinButton, min, max);
439 	}
440 
441 	/**
442 	 * Sets the policy as to whether values are corrected to the
443 	 * nearest step increment when a spin button is activated after
444 	 * providing an invalid value.
445 	 *
446 	 * Params:
447 	 *     snapToTicks = a flag indicating if invalid values should be corrected
448 	 */
449 	public void setSnapToTicks(bool snapToTicks)
450 	{
451 		gtk_spin_button_set_snap_to_ticks(gtkSpinButton, snapToTicks);
452 	}
453 
454 	/**
455 	 * Sets the update behavior of a spin button.
456 	 * This determines whether the spin button is always updated
457 	 * or only when a valid value is set.
458 	 *
459 	 * Params:
460 	 *     policy = a #GtkSpinButtonUpdatePolicy value
461 	 */
462 	public void setUpdatePolicy(GtkSpinButtonUpdatePolicy policy)
463 	{
464 		gtk_spin_button_set_update_policy(gtkSpinButton, policy);
465 	}
466 
467 	/**
468 	 * Sets the value of @spin_button.
469 	 *
470 	 * Params:
471 	 *     value = the new value
472 	 */
473 	public void setValue(double value)
474 	{
475 		gtk_spin_button_set_value(gtkSpinButton, value);
476 	}
477 
478 	/**
479 	 * Sets the flag that determines if a spin button value wraps
480 	 * around to the opposite limit when the upper or lower limit
481 	 * of the range is exceeded.
482 	 *
483 	 * Params:
484 	 *     wrap = a flag indicating if wrapping behavior is performed
485 	 */
486 	public void setWrap(bool wrap)
487 	{
488 		gtk_spin_button_set_wrap(gtkSpinButton, wrap);
489 	}
490 
491 	/**
492 	 * Increment or decrement a spin button’s value in a specified
493 	 * direction by a specified amount.
494 	 *
495 	 * Params:
496 	 *     direction = a #GtkSpinType indicating the direction to spin
497 	 *     increment = step increment to apply in the specified direction
498 	 */
499 	public void spin(GtkSpinType direction, double increment)
500 	{
501 		gtk_spin_button_spin(gtkSpinButton, direction, increment);
502 	}
503 
504 	/**
505 	 * Manually force an update of the spin button.
506 	 */
507 	public void update()
508 	{
509 		gtk_spin_button_update(gtkSpinButton);
510 	}
511 
512 	int[string] connectedSignals;
513 
514 	void delegate(GtkScrollType, SpinButton)[] onChangeValueListeners;
515 	/**
516 	 * The ::change-value signal is a [keybinding signal][GtkBindingSignal]
517 	 * which gets emitted when the user initiates a value change.
518 	 *
519 	 * Applications should not connect to it, but may emit it with
520 	 * g_signal_emit_by_name() if they need to control the cursor
521 	 * programmatically.
522 	 *
523 	 * The default bindings for this signal are Up/Down and PageUp and/PageDown.
524 	 *
525 	 * Params:
526 	 *     scroll = a #GtkScrollType to specify the speed and amount of change
527 	 */
528 	void addOnChangeValue(void delegate(GtkScrollType, SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
529 	{
530 		if ( "change-value" !in connectedSignals )
531 		{
532 			Signals.connectData(
533 				this,
534 				"change-value",
535 				cast(GCallback)&callBackChangeValue,
536 				cast(void*)this,
537 				null,
538 				connectFlags);
539 			connectedSignals["change-value"] = 1;
540 		}
541 		onChangeValueListeners ~= dlg;
542 	}
543 	extern(C) static void callBackChangeValue(GtkSpinButton* spinbuttonStruct, GtkScrollType scroll, SpinButton _spinbutton)
544 	{
545 		foreach ( void delegate(GtkScrollType, SpinButton) dlg; _spinbutton.onChangeValueListeners )
546 		{
547 			dlg(scroll, _spinbutton);
548 		}
549 	}
550 
551 	int delegate(void*, SpinButton)[] onInputListeners;
552 	/**
553 	 * The ::input signal can be used to influence the conversion of
554 	 * the users input into a double value. The signal handler is
555 	 * expected to use gtk_entry_get_text() to retrieve the text of
556 	 * the entry and set @new_value to the new value.
557 	 *
558 	 * The default conversion uses g_strtod().
559 	 *
560 	 * Params:
561 	 *     newValue = return location for the new value
562 	 *
563 	 * Return: %TRUE for a successful conversion, %FALSE if the input
564 	 *     was not handled, and %GTK_INPUT_ERROR if the conversion failed.
565 	 */
566 	void addOnInput(int delegate(void*, SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
567 	{
568 		if ( "input" !in connectedSignals )
569 		{
570 			Signals.connectData(
571 				this,
572 				"input",
573 				cast(GCallback)&callBackInput,
574 				cast(void*)this,
575 				null,
576 				connectFlags);
577 			connectedSignals["input"] = 1;
578 		}
579 		onInputListeners ~= dlg;
580 	}
581 	extern(C) static int callBackInput(GtkSpinButton* spinbuttonStruct, void* newValue, SpinButton _spinbutton)
582 	{
583 		return _spinbutton.onInputListeners[0](newValue, _spinbutton);
584 	}
585 
586 	bool delegate(SpinButton)[] onOutputListeners;
587 	/**
588 	 * The ::output signal can be used to change to formatting
589 	 * of the value that is displayed in the spin buttons entry.
590 	 * |[<!-- language="C" -->
591 	 * // show leading zeros
592 	 * static gboolean
593 	 * on_output (GtkSpinButton *spin,
594 	 * gpointer       data)
595 	 * {
596 	 * GtkAdjustment *adjustment;
597 	 * gchar *text;
598 	 * int value;
599 	 *
600 	 * adjustment = gtk_spin_button_get_adjustment (spin);
601 	 * value = (int)gtk_adjustment_get_value (adjustment);
602 	 * text = g_strdup_printf ("%02d", value);
603 	 * gtk_entry_set_text (GTK_ENTRY (spin), text);
604 	 * g_free (text);
605 	 *
606 	 * return TRUE;
607 	 * }
608 	 * ]|
609 	 *
610 	 * Return: %TRUE if the value has been displayed
611 	 */
612 	void addOnOutput(bool delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
613 	{
614 		if ( "output" !in connectedSignals )
615 		{
616 			Signals.connectData(
617 				this,
618 				"output",
619 				cast(GCallback)&callBackOutput,
620 				cast(void*)this,
621 				null,
622 				connectFlags);
623 			connectedSignals["output"] = 1;
624 		}
625 		onOutputListeners ~= dlg;
626 	}
627 	extern(C) static int callBackOutput(GtkSpinButton* spinbuttonStruct, SpinButton _spinbutton)
628 	{
629 		foreach ( bool delegate(SpinButton) dlg; _spinbutton.onOutputListeners )
630 		{
631 			if ( dlg(_spinbutton) )
632 			{
633 				return 1;
634 			}
635 		}
636 		
637 		return 0;
638 	}
639 
640 	void delegate(SpinButton)[] onValueChangedListeners;
641 	/**
642 	 * The ::value-changed signal is emitted when the value represented by
643 	 * @spinbutton changes. Also see the #GtkSpinButton::output signal.
644 	 */
645 	void addOnValueChanged(void delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
646 	{
647 		if ( "value-changed" !in connectedSignals )
648 		{
649 			Signals.connectData(
650 				this,
651 				"value-changed",
652 				cast(GCallback)&callBackValueChanged,
653 				cast(void*)this,
654 				null,
655 				connectFlags);
656 			connectedSignals["value-changed"] = 1;
657 		}
658 		onValueChangedListeners ~= dlg;
659 	}
660 	extern(C) static void callBackValueChanged(GtkSpinButton* spinbuttonStruct, SpinButton _spinbutton)
661 	{
662 		foreach ( void delegate(SpinButton) dlg; _spinbutton.onValueChangedListeners )
663 		{
664 			dlg(_spinbutton);
665 		}
666 	}
667 
668 	void delegate(SpinButton)[] onWrappedListeners;
669 	/**
670 	 * The ::wrapped signal is emitted right after the spinbutton wraps
671 	 * from its maximum to minimum value or vice-versa.
672 	 *
673 	 * Since: 2.10
674 	 */
675 	void addOnWrapped(void delegate(SpinButton) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
676 	{
677 		if ( "wrapped" !in connectedSignals )
678 		{
679 			Signals.connectData(
680 				this,
681 				"wrapped",
682 				cast(GCallback)&callBackWrapped,
683 				cast(void*)this,
684 				null,
685 				connectFlags);
686 			connectedSignals["wrapped"] = 1;
687 		}
688 		onWrappedListeners ~= dlg;
689 	}
690 	extern(C) static void callBackWrapped(GtkSpinButton* spinbuttonStruct, SpinButton _spinbutton)
691 	{
692 		foreach ( void delegate(SpinButton) dlg; _spinbutton.onWrappedListeners )
693 		{
694 			dlg(_spinbutton);
695 		}
696 	}
697 }