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