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