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.ValueIF; 26 27 private import atk.Range; 28 private import atk.c.functions; 29 public import atk.c.types; 30 private import glib.ListSG; 31 private import glib.Str; 32 private import gobject.ObjectG; 33 private import gobject.Signals; 34 private import gobject.Value; 35 public import gtkc.atktypes; 36 private 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 interface ValueIF{ 182 /** Get the main Gtk struct */ 183 public AtkValue* getValueStruct(bool transferOwnership = false); 184 185 /** the main Gtk struct as a void* */ 186 protected void* getStruct(); 187 188 189 /** */ 190 public static GType getType() 191 { 192 return atk_value_get_type(); 193 } 194 195 /** 196 * Gets the value of this object. 197 * 198 * Deprecated: Since 2.12. Use atk_value_get_value_and_text() 199 * instead. 200 * 201 * Params: 202 * value = a #GValue representing the current accessible value 203 */ 204 public void getCurrentValue(out Value value); 205 206 /** 207 * Gets the minimum increment by which the value of this object may be 208 * changed. If zero, the minimum increment is undefined, which may 209 * mean that it is limited only by the floating point precision of the 210 * platform. 211 * 212 * Returns: the minimum increment by which the value of this 213 * object may be changed. zero if undefined. 214 * 215 * Since: 2.12 216 */ 217 public double getIncrement(); 218 219 /** 220 * Gets the maximum value of this object. 221 * 222 * Deprecated: Since 2.12. Use atk_value_get_range() instead. 223 * 224 * Params: 225 * value = a #GValue representing the maximum accessible value 226 */ 227 public void getMaximumValue(out Value value); 228 229 /** 230 * Gets the minimum increment by which the value of this object may be changed. If zero, 231 * the minimum increment is undefined, which may mean that it is limited only by the 232 * floating point precision of the platform. 233 * 234 * Deprecated: Since 2.12. Use atk_value_get_increment() instead. 235 * 236 * Params: 237 * value = a #GValue representing the minimum increment by which the accessible value may be changed 238 * 239 * Since: 1.12 240 */ 241 public void getMinimumIncrement(out Value value); 242 243 /** 244 * Gets the minimum value of this object. 245 * 246 * Deprecated: Since 2.12. Use atk_value_get_range() instead. 247 * 248 * Params: 249 * value = a #GValue representing the minimum accessible value 250 */ 251 public void getMinimumValue(out Value value); 252 253 /** 254 * Gets the range of this object. 255 * 256 * Returns: a newly allocated #AtkRange 257 * that represents the minimum, maximum and descriptor (if available) 258 * of @obj. NULL if that range is not defined. 259 * 260 * Since: 2.12 261 */ 262 public Range getRange(); 263 264 /** 265 * Gets the list of subranges defined for this object. See #AtkValue 266 * introduction for examples of subranges and when to expose them. 267 * 268 * Returns: an #GSList of 269 * #AtkRange which each of the subranges defined for this object. Free 270 * the returns list with g_slist_free(). 271 * 272 * Since: 2.12 273 */ 274 public ListSG getSubRanges(); 275 276 /** 277 * Gets the current value and the human readable text alternative of 278 * @obj. @text is a newly created string, that must be freed by the 279 * caller. Can be NULL if no descriptor is available. 280 * 281 * Params: 282 * value = address of #gdouble to put the current value of @obj 283 * text = address of #gchar to put the human 284 * readable text alternative for @value 285 * 286 * Since: 2.12 287 */ 288 public void getValueAndText(out double value, out string text); 289 290 /** 291 * Sets the value of this object. 292 * 293 * Deprecated: Since 2.12. Use atk_value_set_value() instead. 294 * 295 * Params: 296 * value = a #GValue which is the desired new accessible value. 297 * 298 * Returns: %TRUE if new value is successfully set, %FALSE otherwise. 299 */ 300 public bool setCurrentValue(Value value); 301 302 /** 303 * Sets the value of this object. 304 * 305 * This method is intended to provide a way to change the value of the 306 * object. In any case, it is possible that the value can't be 307 * modified (ie: a read-only component). If the value changes due this 308 * call, it is possible that the text could change, and will trigger 309 * an #AtkValue::value-changed signal emission. 310 * 311 * Note for implementors: the deprecated atk_value_set_current_value() 312 * method returned TRUE or FALSE depending if the value was assigned 313 * or not. In the practice several implementors were not able to 314 * decide it, and returned TRUE in any case. For that reason it is not 315 * required anymore to return if the value was properly assigned or 316 * not. 317 * 318 * Params: 319 * newValue = a double which is the desired new accessible value. 320 * 321 * Since: 2.12 322 */ 323 public void setValue(double newValue); 324 325 /** 326 * The 'value-changed' signal is emitted when the current value 327 * that represent the object changes. @value is the numerical 328 * representation of this new value. @text is the human 329 * readable text alternative of @value, and can be NULL if it is 330 * not available. Note that if there is a textual description 331 * associated with the new numeric value, that description 332 * should be included regardless of whether or not it has also 333 * changed. 334 * 335 * Example: a password meter whose value changes as the user 336 * types their new password. Appropiate value text would be 337 * "weak", "acceptable" and "strong". 338 * 339 * Params: 340 * value = the new value in a numerical form. 341 * text = human readable text alternative (also called 342 * description) of this object. NULL if not available. 343 * 344 * Since: 2.12 345 */ 346 gulong addOnValueChanged(void delegate(double, string, ValueIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 347 }