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 public  import gtkc.gdktypes;
35 private import gtkc.gtk;
36 public  import gtkc.gtktypes;
37 private import pango.PgLayout;
38 
39 
40 /**
41  * A GtkScale is a slider control used to select a numeric value.
42  * To use it, you’ll probably want to investigate the methods on
43  * its base class, #GtkRange, in addition to the methods for GtkScale itself.
44  * To set the value of a scale, you would normally use gtk_range_set_value().
45  * To detect changes to the value, you would normally use the
46  * #GtkRange::value-changed signal.
47  * 
48  * Note that using the same upper and lower bounds for the #GtkScale (through
49  * the #GtkRange methods) will hide the slider itself. This is useful for
50  * applications that want to show an undeterminate value on the scale, without
51  * changing the layout of the application (such as movie or music players).
52  * 
53  * # GtkScale as GtkBuildable
54  * 
55  * GtkScale supports a custom <marks> element, which can contain multiple
56  * <mark> elements. The “value” and “position” attributes have the same
57  * meaning as gtk_scale_add_mark() parameters of the same name. If the
58  * element is not empty, its content is taken as the markup to show at
59  * the mark. It can be translated with the usual ”translatable” and
60  * “context” attributes.
61  */
62 public class Scale : Range
63 {
64 	/** the main Gtk struct */
65 	protected GtkScale* gtkScale;
66 
67 	/** Get the main Gtk struct */
68 	public GtkScale* getScaleStruct()
69 	{
70 		return gtkScale;
71 	}
72 
73 	/** the main Gtk struct as a void* */
74 	protected override void* getStruct()
75 	{
76 		return cast(void*)gtkScale;
77 	}
78 
79 	protected override void setStruct(GObject* obj)
80 	{
81 		gtkScale = cast(GtkScale*)obj;
82 		super.setStruct(obj);
83 	}
84 
85 	/**
86 	 * Sets our main struct and passes it to the parent class.
87 	 */
88 	public this (GtkScale* gtkScale, bool ownedRef = false)
89 	{
90 		this.gtkScale = gtkScale;
91 		super(cast(GtkRange*)gtkScale, ownedRef);
92 	}
93 
94 	/**
95 	 */
96 
97 	public static GType getType()
98 	{
99 		return gtk_scale_get_type();
100 	}
101 
102 	/**
103 	 * Creates a new #GtkScale.
104 	 *
105 	 * Params:
106 	 *     orientation = the scale’s orientation.
107 	 *     adjustment = the #GtkAdjustment which sets the range
108 	 *         of the scale, or %NULL to create a new adjustment.
109 	 *
110 	 * Return: a new #GtkScale
111 	 *
112 	 * Since: 3.0
113 	 *
114 	 * Throws: ConstructionException GTK+ fails to create the object.
115 	 */
116 	public this(GtkOrientation orientation, Adjustment adjustment)
117 	{
118 		auto p = gtk_scale_new(orientation, (adjustment is null) ? null : adjustment.getAdjustmentStruct());
119 		
120 		if(p is null)
121 		{
122 			throw new ConstructionException("null returned by new");
123 		}
124 		
125 		this(cast(GtkScale*) p);
126 	}
127 
128 	/**
129 	 * Creates a new scale widget with the given orientation that lets the
130 	 * user input a number between @min and @max (including @min and @max)
131 	 * with the increment @step.  @step must be nonzero; it’s the distance
132 	 * the slider moves when using the arrow keys to adjust the scale
133 	 * value.
134 	 *
135 	 * Note that the way in which the precision is derived works best if @step
136 	 * is a power of ten. If the resulting precision is not suitable for your
137 	 * needs, use gtk_scale_set_digits() to correct it.
138 	 *
139 	 * Params:
140 	 *     orientation = the scale’s orientation.
141 	 *     min = minimum value
142 	 *     max = maximum value
143 	 *     step = step increment (tick size) used with keyboard shortcuts
144 	 *
145 	 * Return: a new #GtkScale
146 	 *
147 	 * Since: 3.0
148 	 *
149 	 * Throws: ConstructionException GTK+ fails to create the object.
150 	 */
151 	public this(GtkOrientation orientation, double min, double max, double step)
152 	{
153 		auto p = gtk_scale_new_with_range(orientation, min, max, step);
154 		
155 		if(p is null)
156 		{
157 			throw new ConstructionException("null returned by new_with_range");
158 		}
159 		
160 		this(cast(GtkScale*) p);
161 	}
162 
163 	/**
164 	 * Adds a mark at @value.
165 	 *
166 	 * A mark is indicated visually by drawing a tick mark next to the scale,
167 	 * and GTK+ makes it easy for the user to position the scale exactly at the
168 	 * marks value.
169 	 *
170 	 * If @markup is not %NULL, text is shown next to the tick mark.
171 	 *
172 	 * To remove marks from a scale, use gtk_scale_clear_marks().
173 	 *
174 	 * Params:
175 	 *     value = the value at which the mark is placed, must be between
176 	 *         the lower and upper limits of the scales’ adjustment
177 	 *     position = where to draw the mark. For a horizontal scale, #GTK_POS_TOP
178 	 *         and %GTK_POS_LEFT are drawn above the scale, anything else below.
179 	 *         For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to
180 	 *         the left of the scale, anything else to the right.
181 	 *     markup = Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL
182 	 *
183 	 * Since: 2.16
184 	 */
185 	public void addMark(double value, GtkPositionType position, string markup)
186 	{
187 		gtk_scale_add_mark(gtkScale, value, position, Str.toStringz(markup));
188 	}
189 
190 	/**
191 	 * Removes any marks that have been added with gtk_scale_add_mark().
192 	 *
193 	 * Since: 2.16
194 	 */
195 	public void clearMarks()
196 	{
197 		gtk_scale_clear_marks(gtkScale);
198 	}
199 
200 	/**
201 	 * Gets the number of decimal places that are displayed in the value.
202 	 *
203 	 * Return: the number of decimal places that are displayed
204 	 */
205 	public int getDigits()
206 	{
207 		return gtk_scale_get_digits(gtkScale);
208 	}
209 
210 	/**
211 	 * Returns whether the current value is displayed as a string
212 	 * next to the slider.
213 	 *
214 	 * Return: whether the current value is displayed as a string
215 	 */
216 	public bool getDrawValue()
217 	{
218 		return gtk_scale_get_draw_value(gtkScale) != 0;
219 	}
220 
221 	/**
222 	 * Returns whether the scale has an origin.
223 	 *
224 	 * Return: %TRUE if the scale has an origin.
225 	 *
226 	 * Since: 3.4
227 	 */
228 	public bool getHasOrigin()
229 	{
230 		return gtk_scale_get_has_origin(gtkScale) != 0;
231 	}
232 
233 	/**
234 	 * Gets the #PangoLayout used to display the scale. The returned
235 	 * object is owned by the scale so does not need to be freed by
236 	 * the caller.
237 	 *
238 	 * Return: the #PangoLayout for this scale,
239 	 *     or %NULL if the #GtkScale:draw-value property is %FALSE.
240 	 *
241 	 * Since: 2.4
242 	 */
243 	public PgLayout getLayout()
244 	{
245 		auto p = gtk_scale_get_layout(gtkScale);
246 		
247 		if(p is null)
248 		{
249 			return null;
250 		}
251 		
252 		return ObjectG.getDObject!(PgLayout)(cast(PangoLayout*) p);
253 	}
254 
255 	/**
256 	 * Obtains the coordinates where the scale will draw the
257 	 * #PangoLayout representing the text in the scale. Remember
258 	 * when using the #PangoLayout function you need to convert to
259 	 * and from pixels using PANGO_PIXELS() or #PANGO_SCALE.
260 	 *
261 	 * If the #GtkScale:draw-value property is %FALSE, the return
262 	 * values are undefined.
263 	 *
264 	 * Params:
265 	 *     x = location to store X offset of layout, or %NULL
266 	 *     y = location to store Y offset of layout, or %NULL
267 	 *
268 	 * Since: 2.4
269 	 */
270 	public void getLayoutOffsets(out int x, out int y)
271 	{
272 		gtk_scale_get_layout_offsets(gtkScale, &x, &y);
273 	}
274 
275 	/**
276 	 * Gets the position in which the current value is displayed.
277 	 *
278 	 * Return: the position in which the current value is displayed
279 	 */
280 	public GtkPositionType getValuePos()
281 	{
282 		return gtk_scale_get_value_pos(gtkScale);
283 	}
284 
285 	/**
286 	 * Sets the number of decimal places that are displayed in the value.
287 	 * Also causes the value of the adjustment to be rounded off to this
288 	 * number of digits, so the retrieved value matches the value the user saw.
289 	 *
290 	 * Params:
291 	 *     digits = the number of decimal places to display,
292 	 *         e.g. use 1 to display 1.0, 2 to display 1.00, etc
293 	 */
294 	public void setDigits(int digits)
295 	{
296 		gtk_scale_set_digits(gtkScale, digits);
297 	}
298 
299 	/**
300 	 * Specifies whether the current value is displayed as a string next
301 	 * to the slider.
302 	 *
303 	 * Params:
304 	 *     drawValue = %TRUE to draw the value
305 	 */
306 	public void setDrawValue(bool drawValue)
307 	{
308 		gtk_scale_set_draw_value(gtkScale, drawValue);
309 	}
310 
311 	/**
312 	 * If @has_origin is set to %TRUE (the default),
313 	 * the scale will highlight the part of the scale
314 	 * between the origin (bottom or left side) of the scale
315 	 * and the current value.
316 	 *
317 	 * Params:
318 	 *     hasOrigin = %TRUE if the scale has an origin
319 	 *
320 	 * Since: 3.4
321 	 */
322 	public void setHasOrigin(bool hasOrigin)
323 	{
324 		gtk_scale_set_has_origin(gtkScale, hasOrigin);
325 	}
326 
327 	/**
328 	 * Sets the position in which the current value is displayed.
329 	 *
330 	 * Params:
331 	 *     pos = the position in which the current value is displayed
332 	 */
333 	public void setValuePos(GtkPositionType pos)
334 	{
335 		gtk_scale_set_value_pos(gtkScale, pos);
336 	}
337 
338 	int[string] connectedSignals;
339 
340 	string delegate(double, Scale)[] onFormatValueListeners;
341 	/**
342 	 * Signal which allows you to change how the scale value is displayed.
343 	 * Connect a signal handler which returns an allocated string representing
344 	 * @value. That string will then be used to display the scale's value.
345 	 *
346 	 * Here's an example signal handler which displays a value 1.0 as
347 	 * with "-->1.0<--".
348 	 * |[<!-- language="C" -->
349 	 * static gchar*
350 	 * format_value_callback (GtkScale *scale,
351 	 * gdouble   value)
352 	 * {
353 	 * return g_strdup_printf ("-->\%0.*g<--",
354 	 * gtk_scale_get_digits (scale), value);
355 	 * }
356 	 * ]|
357 	 *
358 	 * Params:
359 	 *     value = the value to format
360 	 *
361 	 * Return: allocated string representing @value
362 	 */
363 	void addOnFormatValue(string delegate(double, Scale) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
364 	{
365 		if ( "format-value" !in connectedSignals )
366 		{
367 			Signals.connectData(
368 				this,
369 				"format-value",
370 				cast(GCallback)&callBackFormatValue,
371 				cast(void*)this,
372 				null,
373 				connectFlags);
374 			connectedSignals["format-value"] = 1;
375 		}
376 		onFormatValueListeners ~= dlg;
377 	}
378 	extern(C) static string callBackFormatValue(GtkScale* scaleStruct, double value, Scale _scale)
379 	{
380 		return _scale.onFormatValueListeners[0](value, _scale);
381 	}
382 }