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 protected class OnValueChangedDelegateWrapper 388 { 389 void delegate(double, string, ValueIF) dlg; 390 gulong handlerId; 391 392 this(void delegate(double, string, ValueIF) dlg) 393 { 394 this.dlg = dlg; 395 onValueChangedListeners ~= this; 396 } 397 398 void remove(OnValueChangedDelegateWrapper source) 399 { 400 foreach(index, wrapper; onValueChangedListeners) 401 { 402 if (wrapper.handlerId == source.handlerId) 403 { 404 onValueChangedListeners[index] = null; 405 onValueChangedListeners = std.algorithm.remove(onValueChangedListeners, index); 406 break; 407 } 408 } 409 } 410 } 411 OnValueChangedDelegateWrapper[] onValueChangedListeners; 412 413 /** 414 * The 'value-changed' signal is emitted when the current value 415 * that represent the object changes. @value is the numerical 416 * representation of this new value. @text is the human 417 * readable text alternative of @value, and can be NULL if it is 418 * not available. Note that if there is a textual description 419 * associated with the new numeric value, that description 420 * should be included regardless of whether or not it has also 421 * changed. 422 * 423 * Example: a password meter whose value changes as the user 424 * types their new password. Appropiate value text would be 425 * "weak", "acceptable" and "strong". 426 * 427 * Params: 428 * value = the new value in a numerical form. 429 * text = human readable text alternative (also called 430 * description) of this object. NULL if not available. 431 * 432 * Since: 2.12 433 */ 434 gulong addOnValueChanged(void delegate(double, string, ValueIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 435 { 436 auto wrapper = new OnValueChangedDelegateWrapper(dlg); 437 wrapper.handlerId = Signals.connectData( 438 this, 439 "value-changed", 440 cast(GCallback)&callBackValueChanged, 441 cast(void*)wrapper, 442 cast(GClosureNotify)&callBackValueChangedDestroy, 443 connectFlags); 444 return wrapper.handlerId; 445 } 446 447 extern(C) static void callBackValueChanged(AtkValue* valueStruct, double value, char* text, OnValueChangedDelegateWrapper wrapper) 448 { 449 wrapper.dlg(value, Str.toString(text), wrapper.outer); 450 } 451 452 extern(C) static void callBackValueChangedDestroy(OnValueChangedDelegateWrapper wrapper, GClosure* closure) 453 { 454 wrapper.remove(wrapper); 455 } 456 }