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.Scale;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gtk.Adjustment;
32 private import gtk.Range;
33 private import gtk.Widget;
34 private import gtk.c.functions;
35 public  import gtk.c.types;
36 public  import gtkc.gtktypes;
37 private import pango.PgLayout;
38 private import std.algorithm;
39 
40 
41 /**
42  * A GtkScale is a slider control used to select a numeric value.
43  * To use it, you’ll probably want to investigate the methods on
44  * its base class, #GtkRange, in addition to the methods for GtkScale itself.
45  * To set the value of a scale, you would normally use gtk_range_set_value().
46  * To detect changes to the value, you would normally use the
47  * #GtkRange::value-changed signal.
48  * 
49  * Note that using the same upper and lower bounds for the #GtkScale (through
50  * the #GtkRange methods) will hide the slider itself. This is useful for
51  * applications that want to show an undeterminate value on the scale, without
52  * changing the layout of the application (such as movie or music players).
53  * 
54  * # GtkScale as GtkBuildable
55  * 
56  * GtkScale supports a custom <marks> element, which can contain multiple
57  * <mark> elements. The “value” and “position” attributes have the same
58  * meaning as gtk_scale_add_mark() parameters of the same name. If the
59  * element is not empty, its content is taken as the markup to show at
60  * the mark. It can be translated with the usual ”translatable” and
61  * “context” attributes.
62  * 
63  * # CSS nodes
64  * 
65  * |[<!-- language="plain" -->
66  * scale[.fine-tune][.marks-before][.marks-after]
67  * ├── marks.top
68  * │   ├── mark
69  * │   ┊    ├── [label]
70  * │   ┊    ╰── indicator
71  * ┊   ┊
72  * │   ╰── mark
73  * ├── [value]
74  * ├── contents
75  * │   ╰── trough
76  * │       ├── slider
77  * │       ├── [highlight]
78  * │       ╰── [fill]
79  * ╰── marks.bottom
80  * ├── mark
81  * ┊    ├── indicator
82  * ┊    ╰── [label]
83  * ╰── mark
84  * ]|
85  * 
86  * GtkScale has a main CSS node with name scale and a subnode for its contents,
87  * with subnodes named trough and slider.
88  * 
89  * The main node gets the style class .fine-tune added when the scale is in
90  * 'fine-tuning' mode.
91  * 
92  * If the scale has an origin (see gtk_scale_set_has_origin()), there is a
93  * subnode with name highlight below the trough node that is used for rendering
94  * the highlighted part of the trough.
95  * 
96  * If the scale is showing a fill level (see gtk_range_set_show_fill_level()),
97  * there is a subnode with name fill below the trough node that is used for
98  * rendering the filled in part of the trough.
99  * 
100  * If marks are present, there is a marks subnode before or after the contents
101  * node, below which each mark gets a node with name mark. The marks nodes get
102  * either the .top or .bottom style class.
103  * 
104  * The mark node has a subnode named indicator. If the mark has text, it also
105  * has a subnode named label. When the mark is either above or left of the
106  * scale, the label subnode is the first when present. Otherwise, the indicator
107  * subnode is the first.
108  * 
109  * The main CSS node gets the 'marks-before' and/or 'marks-after' style classes
110  * added depending on what marks are present.
111  * 
112  * If the scale is displaying the value (see #GtkScale:draw-value), there is
113  * subnode with name value.
114  */
115 public class Scale : Range
116 {
117 	/** the main Gtk struct */
118 	protected GtkScale* gtkScale;
119 
120 	/** Get the main Gtk struct */
121 	public GtkScale* getScaleStruct(bool transferOwnership = false)
122 	{
123 		if (transferOwnership)
124 			ownedRef = false;
125 		return gtkScale;
126 	}
127 
128 	/** the main Gtk struct as a void* */
129 	protected override void* getStruct()
130 	{
131 		return cast(void*)gtkScale;
132 	}
133 
134 	protected override void setStruct(GObject* obj)
135 	{
136 		gtkScale = cast(GtkScale*)obj;
137 		super.setStruct(obj);
138 	}
139 
140 	/**
141 	 * Sets our main struct and passes it to the parent class.
142 	 */
143 	public this (GtkScale* gtkScale, bool ownedRef = false)
144 	{
145 		this.gtkScale = gtkScale;
146 		super(cast(GtkRange*)gtkScale, ownedRef);
147 	}
148 
149 
150 	/** */
151 	public static GType getType()
152 	{
153 		return gtk_scale_get_type();
154 	}
155 
156 	/**
157 	 * Creates a new #GtkScale.
158 	 *
159 	 * Params:
160 	 *     orientation = the scale’s orientation.
161 	 *     adjustment = the #GtkAdjustment which sets the range
162 	 *         of the scale, or %NULL to create a new adjustment.
163 	 *
164 	 * Returns: a new #GtkScale
165 	 *
166 	 * Since: 3.0
167 	 *
168 	 * Throws: ConstructionException GTK+ fails to create the object.
169 	 */
170 	public this(GtkOrientation orientation, Adjustment adjustment)
171 	{
172 		auto p = gtk_scale_new(orientation, (adjustment is null) ? null : adjustment.getAdjustmentStruct());
173 
174 		if(p is null)
175 		{
176 			throw new ConstructionException("null returned by new");
177 		}
178 
179 		this(cast(GtkScale*) p);
180 	}
181 
182 	/**
183 	 * Creates a new scale widget with the given orientation that lets the
184 	 * user input a number between @min and @max (including @min and @max)
185 	 * with the increment @step.  @step must be nonzero; it’s the distance
186 	 * the slider moves when using the arrow keys to adjust the scale
187 	 * value.
188 	 *
189 	 * Note that the way in which the precision is derived works best if @step
190 	 * is a power of ten. If the resulting precision is not suitable for your
191 	 * needs, use gtk_scale_set_digits() to correct it.
192 	 *
193 	 * Params:
194 	 *     orientation = the scale’s orientation.
195 	 *     min = minimum value
196 	 *     max = maximum value
197 	 *     step = step increment (tick size) used with keyboard shortcuts
198 	 *
199 	 * Returns: a new #GtkScale
200 	 *
201 	 * Since: 3.0
202 	 *
203 	 * Throws: ConstructionException GTK+ fails to create the object.
204 	 */
205 	public this(GtkOrientation orientation, double min, double max, double step)
206 	{
207 		auto p = gtk_scale_new_with_range(orientation, min, max, step);
208 
209 		if(p is null)
210 		{
211 			throw new ConstructionException("null returned by new_with_range");
212 		}
213 
214 		this(cast(GtkScale*) p);
215 	}
216 
217 	/**
218 	 * Adds a mark at @value.
219 	 *
220 	 * A mark is indicated visually by drawing a tick mark next to the scale,
221 	 * and GTK+ makes it easy for the user to position the scale exactly at the
222 	 * marks value.
223 	 *
224 	 * If @markup is not %NULL, text is shown next to the tick mark.
225 	 *
226 	 * To remove marks from a scale, use gtk_scale_clear_marks().
227 	 *
228 	 * Params:
229 	 *     value = the value at which the mark is placed, must be between
230 	 *         the lower and upper limits of the scales’ adjustment
231 	 *     position = where to draw the mark. For a horizontal scale, #GTK_POS_TOP
232 	 *         and %GTK_POS_LEFT are drawn above the scale, anything else below.
233 	 *         For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to
234 	 *         the left of the scale, anything else to the right.
235 	 *     markup = Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL
236 	 *
237 	 * Since: 2.16
238 	 */
239 	public void addMark(double value, GtkPositionType position, string markup)
240 	{
241 		gtk_scale_add_mark(gtkScale, value, position, Str.toStringz(markup));
242 	}
243 
244 	/**
245 	 * Removes any marks that have been added with gtk_scale_add_mark().
246 	 *
247 	 * Since: 2.16
248 	 */
249 	public void clearMarks()
250 	{
251 		gtk_scale_clear_marks(gtkScale);
252 	}
253 
254 	/**
255 	 * Gets the number of decimal places that are displayed in the value.
256 	 *
257 	 * Returns: the number of decimal places that are displayed
258 	 */
259 	public int getDigits()
260 	{
261 		return gtk_scale_get_digits(gtkScale);
262 	}
263 
264 	/**
265 	 * Returns whether the current value is displayed as a string
266 	 * next to the slider.
267 	 *
268 	 * Returns: whether the current value is displayed as a string
269 	 */
270 	public bool getDrawValue()
271 	{
272 		return gtk_scale_get_draw_value(gtkScale) != 0;
273 	}
274 
275 	/**
276 	 * Returns whether the scale has an origin.
277 	 *
278 	 * Returns: %TRUE if the scale has an origin.
279 	 *
280 	 * Since: 3.4
281 	 */
282 	public bool getHasOrigin()
283 	{
284 		return gtk_scale_get_has_origin(gtkScale) != 0;
285 	}
286 
287 	/**
288 	 * Gets the #PangoLayout used to display the scale. The returned
289 	 * object is owned by the scale so does not need to be freed by
290 	 * the caller.
291 	 *
292 	 * Returns: the #PangoLayout for this scale,
293 	 *     or %NULL if the #GtkScale:draw-value property is %FALSE.
294 	 *
295 	 * Since: 2.4
296 	 */
297 	public PgLayout getLayout()
298 	{
299 		auto p = gtk_scale_get_layout(gtkScale);
300 
301 		if(p is null)
302 		{
303 			return null;
304 		}
305 
306 		return ObjectG.getDObject!(PgLayout)(cast(PangoLayout*) p);
307 	}
308 
309 	/**
310 	 * Obtains the coordinates where the scale will draw the
311 	 * #PangoLayout representing the text in the scale. Remember
312 	 * when using the #PangoLayout function you need to convert to
313 	 * and from pixels using PANGO_PIXELS() or #PANGO_SCALE.
314 	 *
315 	 * If the #GtkScale:draw-value property is %FALSE, the return
316 	 * values are undefined.
317 	 *
318 	 * Params:
319 	 *     x = location to store X offset of layout, or %NULL
320 	 *     y = location to store Y offset of layout, or %NULL
321 	 *
322 	 * Since: 2.4
323 	 */
324 	public void getLayoutOffsets(out int x, out int y)
325 	{
326 		gtk_scale_get_layout_offsets(gtkScale, &x, &y);
327 	}
328 
329 	/**
330 	 * Gets the position in which the current value is displayed.
331 	 *
332 	 * Returns: the position in which the current value is displayed
333 	 */
334 	public GtkPositionType getValuePos()
335 	{
336 		return gtk_scale_get_value_pos(gtkScale);
337 	}
338 
339 	/**
340 	 * Sets the number of decimal places that are displayed in the value. Also
341 	 * causes the value of the adjustment to be rounded to this number of digits,
342 	 * so the retrieved value matches the displayed one, if #GtkScale:draw-value is
343 	 * %TRUE when the value changes. If you want to enforce rounding the value when
344 	 * #GtkScale:draw-value is %FALSE, you can set #GtkRange:round-digits instead.
345 	 *
346 	 * Note that rounding to a small number of digits can interfere with
347 	 * the smooth autoscrolling that is built into #GtkScale. As an alternative,
348 	 * you can use the #GtkScale::format-value signal to format the displayed
349 	 * value yourself.
350 	 *
351 	 * Params:
352 	 *     digits = the number of decimal places to display,
353 	 *         e.g. use 1 to display 1.0, 2 to display 1.00, etc
354 	 */
355 	public void setDigits(int digits)
356 	{
357 		gtk_scale_set_digits(gtkScale, digits);
358 	}
359 
360 	/**
361 	 * Specifies whether the current value is displayed as a string next
362 	 * to the slider.
363 	 *
364 	 * Params:
365 	 *     drawValue = %TRUE to draw the value
366 	 */
367 	public void setDrawValue(bool drawValue)
368 	{
369 		gtk_scale_set_draw_value(gtkScale, drawValue);
370 	}
371 
372 	/**
373 	 * If #GtkScale:has-origin is set to %TRUE (the default), the scale will
374 	 * highlight the part of the trough between the origin (bottom or left side)
375 	 * and the current value.
376 	 *
377 	 * Params:
378 	 *     hasOrigin = %TRUE if the scale has an origin
379 	 *
380 	 * Since: 3.4
381 	 */
382 	public void setHasOrigin(bool hasOrigin)
383 	{
384 		gtk_scale_set_has_origin(gtkScale, hasOrigin);
385 	}
386 
387 	/**
388 	 * Sets the position in which the current value is displayed.
389 	 *
390 	 * Params:
391 	 *     pos = the position in which the current value is displayed
392 	 */
393 	public void setValuePos(GtkPositionType pos)
394 	{
395 		gtk_scale_set_value_pos(gtkScale, pos);
396 	}
397 
398 	protected class OnFormatValueDelegateWrapper
399 	{
400 		string delegate(double, Scale) dlg;
401 		gulong handlerId;
402 
403 		this(string delegate(double, Scale) dlg)
404 		{
405 			this.dlg = dlg;
406 			onFormatValueListeners ~= this;
407 		}
408 
409 		void remove(OnFormatValueDelegateWrapper source)
410 		{
411 			foreach(index, wrapper; onFormatValueListeners)
412 			{
413 				if (wrapper.handlerId == source.handlerId)
414 				{
415 					onFormatValueListeners[index] = null;
416 					onFormatValueListeners = std.algorithm.remove(onFormatValueListeners, index);
417 					break;
418 				}
419 			}
420 		}
421 	}
422 	OnFormatValueDelegateWrapper[] onFormatValueListeners;
423 
424 	/**
425 	 * Signal which allows you to change how the scale value is displayed.
426 	 * Connect a signal handler which returns an allocated string representing
427 	 * @value. That string will then be used to display the scale's value.
428 	 *
429 	 * If no user-provided handlers are installed, the value will be displayed on
430 	 * its own, rounded according to the value of the #GtkScale:digits property.
431 	 *
432 	 * Here's an example signal handler which displays a value 1.0 as
433 	 * with "-->1.0<--".
434 	 * |[<!-- language="C" -->
435 	 * static gchar*
436 	 * format_value_callback (GtkScale *scale,
437 	 * gdouble   value)
438 	 * {
439 	 * return g_strdup_printf ("-->\%0.*g<--",
440 	 * gtk_scale_get_digits (scale), value);
441 	 * }
442 	 * ]|
443 	 *
444 	 * Params:
445 	 *     value = the value to format
446 	 *
447 	 * Returns: allocated string representing @value
448 	 */
449 	gulong addOnFormatValue(string delegate(double, Scale) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
450 	{
451 		auto wrapper = new OnFormatValueDelegateWrapper(dlg);
452 		wrapper.handlerId = Signals.connectData(
453 			this,
454 			"format-value",
455 			cast(GCallback)&callBackFormatValue,
456 			cast(void*)wrapper,
457 			cast(GClosureNotify)&callBackFormatValueDestroy,
458 			connectFlags);
459 		return wrapper.handlerId;
460 	}
461 
462 	extern(C) static string callBackFormatValue(GtkScale* scaleStruct, double value, OnFormatValueDelegateWrapper wrapper)
463 	{
464 		return wrapper.dlg(value, wrapper.outer);
465 	}
466 
467 	extern(C) static void callBackFormatValueDestroy(OnFormatValueDelegateWrapper wrapper, GClosure* closure)
468 	{
469 		wrapper.remove(wrapper);
470 	}
471 }