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