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 atk.ValueT;
26 
27 public  import atk.Range;
28 public  import atk.c.functions;
29 public  import atk.c.types;
30 public  import glib.ListSG;
31 public  import glib.Str;
32 public  import gobject.ObjectG;
33 public  import gobject.Signals;
34 public  import gobject.Value;
35 public  import gtkc.atktypes;
36 public  import std.algorithm;
37 
38 
39 /**
40  * #AtkValue should be implemented for components which either display
41  * a value from a bounded range, or which allow the user to specify a
42  * value from a bounded range, or both. For instance, most sliders and
43  * range controls, as well as dials, should have #AtkObject
44  * representations which implement #AtkValue on the component's
45  * behalf. #AtKValues may be read-only, in which case attempts to
46  * alter the value return would fail.
47  * 
48  * <refsect1 id="current-value-text">
49  * <title>On the subject of current value text</title>
50  * <para>
51  * In addition to providing the current value, implementors can
52  * optionally provide an end-user-consumable textual description
53  * associated with this value. This description should be included
54  * when the numeric value fails to convey the full, on-screen
55  * representation seen by users.
56  * </para>
57  * 
58  * <example>
59  * <title>Password strength</title>
60  * A password strength meter whose value changes as the user types
61  * their new password. Red is used for values less than 4.0, yellow
62  * for values between 4.0 and 7.0, and green for values greater than
63  * 7.0. In this instance, value text should be provided by the
64  * implementor. Appropriate value text would be "weak", "acceptable,"
65  * and "strong" respectively.
66  * </example>
67  * 
68  * A level bar whose value changes to reflect the battery charge. The
69  * color remains the same regardless of the charge and there is no
70  * on-screen text reflecting the fullness of the battery. In this
71  * case, because the position within the bar is the only indication
72  * the user has of the current charge, value text should not be
73  * provided by the implementor.
74  * 
75  * <refsect2 id="implementor-notes">
76  * <title>Implementor Notes</title>
77  * <para>
78  * Implementors should bear in mind that assistive technologies will
79  * likely prefer the value text provided over the numeric value when
80  * presenting a widget's value. As a result, strings not intended for
81  * end users should not be exposed in the value text, and strings
82  * which are exposed should be localized. In the case of widgets which
83  * display value text on screen, for instance through a separate label
84  * in close proximity to the value-displaying widget, it is still
85  * expected that implementors will expose the value text using the
86  * above API.
87  * </para>
88  * 
89  * <para>
90  * #AtkValue should NOT be implemented for widgets whose displayed
91  * value is not reflective of a meaningful amount. For instance, a
92  * progress pulse indicator whose value alternates between 0.0 and 1.0
93  * to indicate that some process is still taking place should not
94  * implement #AtkValue because the current value does not reflect
95  * progress towards completion.
96  * </para>
97  * </refsect2>
98  * </refsect1>
99  * 
100  * <refsect1 id="ranges">
101  * <title>On the subject of ranges</title>
102  * <para>
103  * In addition to providing the minimum and maximum values,
104  * implementors can optionally provide details about subranges
105  * associated with the widget. These details should be provided by the
106  * implementor when both of the following are communicated visually to
107  * the end user:
108  * </para>
109  * <itemizedlist>
110  * <listitem>The existence of distinct ranges such as "weak",
111  * "acceptable", and "strong" indicated by color, bar tick marks,
112  * and/or on-screen text.</listitem>
113  * <listitem>Where the current value stands within a given subrange,
114  * for instance illustrating progression from very "weak" towards
115  * nearly "acceptable" through changes in shade and/or position on
116  * the bar within the "weak" subrange.</listitem>
117  * </itemizedlist>
118  * <para>
119  * If both of the above do not apply to the widget, it should be
120  * sufficient to expose the numeric value, along with the value text
121  * if appropriate, to make the widget accessible.
122  * </para>
123  * 
124  * <refsect2 id="ranges-implementor-notes">
125  * <title>Implementor Notes</title>
126  * <para>
127  * If providing subrange details is deemed necessary, all possible
128  * values of the widget are expected to fall within one of the
129  * subranges defined by the implementor.
130  * </para>
131  * </refsect2>
132  * </refsect1>
133  * 
134  * <refsect1 id="localization">
135  * <title>On the subject of localization of end-user-consumable text
136  * values</title>
137  * <para>
138  * Because value text and subrange descriptors are human-consumable,
139  * implementors are expected to provide localized strings which can be
140  * directly presented to end users via their assistive technology. In
141  * order to simplify this for implementors, implementors can use
142  * atk_value_type_get_localized_name() with the following
143  * already-localized constants for commonly-needed values can be used:
144  * </para>
145  * 
146  * <itemizedlist>
147  * <listitem>ATK_VALUE_VERY_WEAK</listitem>
148  * <listitem>ATK_VALUE_WEAK</listitem>
149  * <listitem>ATK_VALUE_ACCEPTABLE</listitem>
150  * <listitem>ATK_VALUE_STRONG</listitem>
151  * <listitem>ATK_VALUE_VERY_STRONG</listitem>
152  * <listitem>ATK_VALUE_VERY_LOW</listitem>
153  * <listitem>ATK_VALUE_LOW</listitem>
154  * <listitem>ATK_VALUE_MEDIUM</listitem>
155  * <listitem>ATK_VALUE_HIGH</listitem>
156  * <listitem>ATK_VALUE_VERY_HIGH</listitem>
157  * <listitem>ATK_VALUE_VERY_BAD</listitem>
158  * <listitem>ATK_VALUE_BAD</listitem>
159  * <listitem>ATK_VALUE_GOOD</listitem>
160  * <listitem>ATK_VALUE_VERY_GOOD</listitem>
161  * <listitem>ATK_VALUE_BEST</listitem>
162  * <listitem>ATK_VALUE_SUBSUBOPTIMAL</listitem>
163  * <listitem>ATK_VALUE_SUBOPTIMAL</listitem>
164  * <listitem>ATK_VALUE_OPTIMAL</listitem>
165  * </itemizedlist>
166  * <para>
167  * Proposals for additional constants, along with their use cases,
168  * should be submitted to the GNOME Accessibility Team.
169  * </para>
170  * </refsect1>
171  * 
172  * <refsect1 id="changes">
173  * <title>On the subject of changes</title>
174  * <para>
175  * Note that if there is a textual description associated with the new
176  * numeric value, that description should be included regardless of
177  * whether or not it has also changed.
178  * </para>
179  * </refsect1>
180  */
181 public template ValueT(TStruct)
182 {
183 	/** Get the main Gtk struct */
184 	public AtkValue* getValueStruct(bool transferOwnership = false)
185 	{
186 		if (transferOwnership)
187 			ownedRef = false;
188 		return cast(AtkValue*)getStruct();
189 	}
190 
191 
192 	/**
193 	 * Gets the value of this object.
194 	 *
195 	 * Deprecated: Since 2.12. Use atk_value_get_value_and_text()
196 	 * instead.
197 	 *
198 	 * Params:
199 	 *     value = a #GValue representing the current accessible value
200 	 */
201 	public void getCurrentValue(out Value value)
202 	{
203 		GValue* outvalue = gMalloc!GValue();
204 
205 		atk_value_get_current_value(getValueStruct(), outvalue);
206 
207 		value = ObjectG.getDObject!(Value)(outvalue, true);
208 	}
209 
210 	/**
211 	 * Gets the minimum increment by which the value of this object may be
212 	 * changed.  If zero, the minimum increment is undefined, which may
213 	 * mean that it is limited only by the floating point precision of the
214 	 * platform.
215 	 *
216 	 * Returns: the minimum increment by which the value of this
217 	 *     object may be changed. zero if undefined.
218 	 *
219 	 * Since: 2.12
220 	 */
221 	public double getIncrement()
222 	{
223 		return atk_value_get_increment(getValueStruct());
224 	}
225 
226 	/**
227 	 * Gets the maximum value of this object.
228 	 *
229 	 * Deprecated: Since 2.12. Use atk_value_get_range() instead.
230 	 *
231 	 * Params:
232 	 *     value = a #GValue representing the maximum accessible value
233 	 */
234 	public void getMaximumValue(out Value value)
235 	{
236 		GValue* outvalue = gMalloc!GValue();
237 
238 		atk_value_get_maximum_value(getValueStruct(), outvalue);
239 
240 		value = ObjectG.getDObject!(Value)(outvalue, true);
241 	}
242 
243 	/**
244 	 * Gets the minimum increment by which the value of this object may be changed.  If zero,
245 	 * the minimum increment is undefined, which may mean that it is limited only by the
246 	 * floating point precision of the platform.
247 	 *
248 	 * Deprecated: Since 2.12. Use atk_value_get_increment() instead.
249 	 *
250 	 * Params:
251 	 *     value = a #GValue representing the minimum increment by which the accessible value may be changed
252 	 *
253 	 * Since: 1.12
254 	 */
255 	public void getMinimumIncrement(out Value value)
256 	{
257 		GValue* outvalue = gMalloc!GValue();
258 
259 		atk_value_get_minimum_increment(getValueStruct(), outvalue);
260 
261 		value = ObjectG.getDObject!(Value)(outvalue, true);
262 	}
263 
264 	/**
265 	 * Gets the minimum value of this object.
266 	 *
267 	 * Deprecated: Since 2.12. Use atk_value_get_range() instead.
268 	 *
269 	 * Params:
270 	 *     value = a #GValue representing the minimum accessible value
271 	 */
272 	public void getMinimumValue(out Value value)
273 	{
274 		GValue* outvalue = gMalloc!GValue();
275 
276 		atk_value_get_minimum_value(getValueStruct(), outvalue);
277 
278 		value = ObjectG.getDObject!(Value)(outvalue, true);
279 	}
280 
281 	/**
282 	 * Gets the range of this object.
283 	 *
284 	 * Returns: a newly allocated #AtkRange
285 	 *     that represents the minimum, maximum and descriptor (if available)
286 	 *     of @obj. NULL if that range is not defined.
287 	 *
288 	 * Since: 2.12
289 	 */
290 	public Range getRange()
291 	{
292 		auto p = atk_value_get_range(getValueStruct());
293 
294 		if(p is null)
295 		{
296 			return null;
297 		}
298 
299 		return ObjectG.getDObject!(Range)(cast(AtkRange*) p, true);
300 	}
301 
302 	/**
303 	 * Gets the list of subranges defined for this object. See #AtkValue
304 	 * introduction for examples of subranges and when to expose them.
305 	 *
306 	 * Returns: an #GSList of
307 	 *     #AtkRange which each of the subranges defined for this object. Free
308 	 *     the returns list with g_slist_free().
309 	 *
310 	 * Since: 2.12
311 	 */
312 	public ListSG getSubRanges()
313 	{
314 		auto p = atk_value_get_sub_ranges(getValueStruct());
315 
316 		if(p is null)
317 		{
318 			return null;
319 		}
320 
321 		return new ListSG(cast(GSList*) p, true);
322 	}
323 
324 	/**
325 	 * Gets the current value and the human readable text alternative of
326 	 * @obj. @text is a newly created string, that must be freed by the
327 	 * caller. Can be NULL if no descriptor is available.
328 	 *
329 	 * Params:
330 	 *     value = address of #gdouble to put the current value of @obj
331 	 *     text = address of #gchar to put the human
332 	 *         readable text alternative for @value
333 	 *
334 	 * Since: 2.12
335 	 */
336 	public void getValueAndText(out double value, out string text)
337 	{
338 		char* outtext = null;
339 
340 		atk_value_get_value_and_text(getValueStruct(), &value, &outtext);
341 
342 		text = Str.toString(outtext);
343 	}
344 
345 	/**
346 	 * Sets the value of this object.
347 	 *
348 	 * Deprecated: Since 2.12. Use atk_value_set_value() instead.
349 	 *
350 	 * Params:
351 	 *     value = a #GValue which is the desired new accessible value.
352 	 *
353 	 * Returns: %TRUE if new value is successfully set, %FALSE otherwise.
354 	 */
355 	public bool setCurrentValue(Value value)
356 	{
357 		return atk_value_set_current_value(getValueStruct(), (value is null) ? null : value.getValueStruct()) != 0;
358 	}
359 
360 	/**
361 	 * Sets the value of this object.
362 	 *
363 	 * This method is intended to provide a way to change the value of the
364 	 * object. In any case, it is possible that the value can't be
365 	 * modified (ie: a read-only component). If the value changes due this
366 	 * call, it is possible that the text could change, and will trigger
367 	 * an #AtkValue::value-changed signal emission.
368 	 *
369 	 * Note for implementors: the deprecated atk_value_set_current_value()
370 	 * method returned TRUE or FALSE depending if the value was assigned
371 	 * or not. In the practice several implementors were not able to
372 	 * decide it, and returned TRUE in any case. For that reason it is not
373 	 * required anymore to return if the value was properly assigned or
374 	 * not.
375 	 *
376 	 * Params:
377 	 *     newValue = a double which is the desired new accessible value.
378 	 *
379 	 * Since: 2.12
380 	 */
381 	public void setValue(double newValue)
382 	{
383 		atk_value_set_value(getValueStruct(), newValue);
384 	}
385 
386 	protected class OnValueChangedDelegateWrapper
387 	{
388 		void delegate(double, string, ValueIF) dlg;
389 		gulong handlerId;
390 
391 		this(void delegate(double, string, ValueIF) dlg)
392 		{
393 			this.dlg = dlg;
394 			onValueChangedListeners ~= this;
395 		}
396 
397 		void remove(OnValueChangedDelegateWrapper source)
398 		{
399 			foreach(index, wrapper; onValueChangedListeners)
400 			{
401 				if (wrapper.handlerId == source.handlerId)
402 				{
403 					onValueChangedListeners[index] = null;
404 					onValueChangedListeners = std.algorithm.remove(onValueChangedListeners, index);
405 					break;
406 				}
407 			}
408 		}
409 	}
410 	OnValueChangedDelegateWrapper[] onValueChangedListeners;
411 
412 	/**
413 	 * The 'value-changed' signal is emitted when the current value
414 	 * that represent the object changes. @value is the numerical
415 	 * representation of this new value.  @text is the human
416 	 * readable text alternative of @value, and can be NULL if it is
417 	 * not available. Note that if there is a textual description
418 	 * associated with the new numeric value, that description
419 	 * should be included regardless of whether or not it has also
420 	 * changed.
421 	 *
422 	 * Example: a password meter whose value changes as the user
423 	 * types their new password. Appropiate value text would be
424 	 * "weak", "acceptable" and "strong".
425 	 *
426 	 * Params:
427 	 *     value = the new value in a numerical form.
428 	 *     text = human readable text alternative (also called
429 	 *         description) of this object. NULL if not available.
430 	 *
431 	 * Since: 2.12
432 	 */
433 	gulong addOnValueChanged(void delegate(double, string, ValueIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
434 	{
435 		auto wrapper = new OnValueChangedDelegateWrapper(dlg);
436 		wrapper.handlerId = Signals.connectData(
437 			this,
438 			"value-changed",
439 			cast(GCallback)&callBackValueChanged,
440 			cast(void*)wrapper,
441 			cast(GClosureNotify)&callBackValueChangedDestroy,
442 			connectFlags);
443 		return wrapper.handlerId;
444 	}
445 
446 	extern(C) static void callBackValueChanged(AtkValue* valueStruct, double value, char* text, OnValueChangedDelegateWrapper wrapper)
447 	{
448 		wrapper.dlg(value, Str.toString(text), wrapper.outer);
449 	}
450 
451 	extern(C) static void callBackValueChangedDestroy(OnValueChangedDelegateWrapper wrapper, GClosure* closure)
452 	{
453 		wrapper.remove(wrapper);
454 	}
455 }