doc: improve documentation of AtkAttribute and AtkAttributeSet

[platform/upstream/atk.git] / atk / atkvalue.c

diff --git a/atk/atkvalue.c b/atk/atkvalue.c
index 3ed6807..2a6b083 100755 (executable)
--- a/atk/atkvalue.c
+++ b/atk/atkvalue.c
@@ -1,5 +1,5 @@
 /* ATK -  Accessibility Toolkit
- * Copyright 2001 Sun Microsystems Inc.
+ * Copyright 2001, 2002, 2003 Sun Microsystems Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -17,10 +17,27 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include <string.h>
 #include "atkvalue.h"
 
+/**
+ * SECTION:atkvalue
+ * @Short_description: The ATK interface implemented by valuators and
+ *  components which display or select a value from a bounded range of
+ *  values.
+ * @Title:AtkValue
+ *
+ * #AtkValue should be implemented for components which either display
+ * a value from a bounded range, or which allow the user to specify a
+ * value from a bounded range, or both.  For instance, most sliders
+ * and range controls, as well as dials, should have #AtkObject
+ * representations which implement #AtkValue on the component's
+ * behalf.  #AtKValues may be read-only, in which case attempts to
+ * alter the value return FALSE to indicate failure.
+ */
+
 GType
-atk_value_get_type ()
+atk_value_get_type (void)
 {
   static GType type = 0;
 
@@ -52,14 +69,20 @@ atk_value_get_current_value (AtkValue *obj,
 {
   AtkValueIface *iface;
 
-  g_return_if_fail (obj != NULL);
   g_return_if_fail (value != NULL);
   g_return_if_fail (ATK_IS_VALUE (obj));
 
   iface = ATK_VALUE_GET_IFACE (obj);
 
   if (iface->get_current_value)
-    (iface->get_current_value) (obj, value);
+    {
+      if (G_IS_VALUE (value))
+        g_value_unset (value);
+      else
+        memset (value, 0, sizeof (*value));
+
+      (iface->get_current_value) (obj, value);
+    }
 }
 
 /**
@@ -75,14 +98,20 @@ atk_value_get_maximum_value  (AtkValue *obj,
 {
   AtkValueIface *iface;
 
-  g_return_if_fail (obj != NULL);
   g_return_if_fail (value != NULL);
   g_return_if_fail (ATK_IS_VALUE (obj));
 
   iface = ATK_VALUE_GET_IFACE (obj);
 
   if (iface->get_maximum_value)
-    (iface->get_maximum_value) (obj, value);
+    {
+      if (G_IS_VALUE (value))
+        g_value_unset (value);
+      else
+        memset (value, 0, sizeof (*value));
+
+      (iface->get_maximum_value) (obj, value);
+    }
 }
 
 /**
@@ -98,14 +127,53 @@ atk_value_get_minimum_value (AtkValue *obj,
 {
   AtkValueIface *iface;
 
-  g_return_if_fail (obj != NULL);
   g_return_if_fail (value != NULL);
   g_return_if_fail (ATK_IS_VALUE (obj));
 
   iface = ATK_VALUE_GET_IFACE (obj);
 
   if (iface->get_minimum_value)
-    (iface->get_minimum_value) (obj, value);
+    {
+      if (G_IS_VALUE (value))
+        g_value_unset (value);
+      else
+        memset (value, 0, sizeof (*value));
+
+      (iface->get_minimum_value) (obj, value);
+    }
+}
+
+/**
+ * atk_value_get_minimum_increment:
+ * @obj: a GObject instance that implements AtkValueIface
+ * @value: a #GValue representing the minimum increment by which the accessible value may be changed
+ *
+ * Gets the minimum increment by which the value of this object may be changed.  If zero,
+ * the minimum increment is undefined, which may mean that it is limited only by the 
+ * floating point precision of the platform.
+ *
+ * Since: 1.12
+ **/
+void
+atk_value_get_minimum_increment (AtkValue *obj,
+                             GValue   *value)
+{
+  AtkValueIface *iface;
+
+  g_return_if_fail (value != NULL);
+  g_return_if_fail (ATK_IS_VALUE (obj));
+
+  iface = ATK_VALUE_GET_IFACE (obj);
+
+  if (iface->get_minimum_increment)
+    {
+      if (G_IS_VALUE (value))
+        g_value_unset (value);
+      else
+        memset (value, 0, sizeof (*value));
+
+      (iface->get_minimum_increment) (obj, value);
+    }
 }
 
 /**
@@ -123,8 +191,6 @@ atk_value_set_current_value (AtkValue       *obj,
 {
   AtkValueIface *iface;
 
-  g_return_val_if_fail (obj != NULL, FALSE);
-  g_return_val_if_fail (value != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_VALUE (obj), FALSE);
   g_return_val_if_fail (G_IS_VALUE (value), FALSE);