Add property accessible-table-caption-object. This addresses bug #74814.

2003-01-21  Padraig O'Briain  <padraig.obriain@sun.com>

	* atk/atkobject.c: Add property accessible-table-caption-object.
	This addresses bug #74814.

	* atk/atkobject.h: Move some documentation from template file to
	avoid warnings when building.

	* atk/atkrelation.c: Add new properties relation and target.
	This addresses bug #72426.

	* atktext.[ch]: Add new functions atk_text_get_range_extents and
	atk_text_get_bounded_ranges.
	Also added data structures AtkTextRectangle and AtkTextRange, enum
	AtkTextClipType and helper function  atk_text_free_ranges.
	This addresses bug #100943.
	(atk_text_get_character_extents): Ensure that the reported width is
	not negative. This fixes bug #102954)

	* docs/atk-sections.txt: Add new functions and data items.

	* docs/tmpl/atk-object.sgml: Remove some docuementation and put in
	atkobject.h. Add reference to accessible-table-caption-object.

	* docs/tmpl/atk-relation.sgml: Add new properties

	* docs/tmpl/atktext.sgml: Add new functions and data items.

10 files changed, 629 insertions, 32 deletions

diff --git a/ChangeLog b/ChangeLog
index 2d71b8b..b8e3b74 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,33 @@
-003-01-20  Padraig O'Briain  <padraig.obriain@sun.com>
+2003-01-21  Padraig O'Briain  <padraig.obriain@sun.com>
+
+	* atk/atkobject.c: Add property accessible-table-caption-object.
+	This addresses bug #74814.
+
+	* atk/atkobject.h: Move some documentation from template file to
+	avoid warnings when building.
+
+	* atk/atkrelation.c: Add new properties relation and target.
+	This addresses bug #72426.
+
+	* atktext.[ch]: Add new functions atk_text_get_range_extents and
+	atk_text_get_bounded_ranges.
+	Also added data structures AtkTextRectangle and AtkTextRange, enum
+	AtkTextClipType and helper function  atk_text_free_ranges.
+	This addresses bug #100943.
+	(atk_text_get_character_extents): Ensure that the reported width is 
+	not negative. This fixes bug #102954)
+
+	* docs/atk-sections.txt: Add new functions and data items.
+
+	* docs/tmpl/atk-object.sgml: Remove some docuementation and put in 
+	atkobject.h. Add reference to accessible-table-caption-object.
+
+	* docs/tmpl/atk-relation.sgml: Add new properties
+
+	* docs/tmpl/atktext.sgml: Add new functions and data items.
+
+
+2003-01-20  Padraig O'Briain  <padraig.obriain@sun.com>
 
 	* ===== Released 1.2.2=====
 
diff --git a/atk/atkobject.c b/atk/atkobject.c
index 0c9c220..c746885 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -45,6 +45,7 @@ enum
   PROP_TABLE_ROW_DESCRIPTION,
   PROP_TABLE_ROW_HEADER,
   PROP_TABLE_SUMMARY,
+  PROP_TABLE_CAPTION_OBJECT,
   PROP_LAST         /* gobject convention */
 };
 
@@ -121,6 +122,7 @@ static const gchar* atk_object_name_property_table_column_header = "accessible-t
 static const gchar* atk_object_name_property_table_row_description = "accessible-table-row-description";
 static const gchar* atk_object_name_property_table_row_header = "accessible-table-row-header";
 static const gchar* atk_object_name_property_table_summary = "accessible-table-summary";
+static const gchar* atk_object_name_property_table_caption_object = "accessible-table-caption-object";
 
 GType
 atk_object_get_type (void)
@@ -250,7 +252,7 @@ atk_object_class_init (AtkObjectClass *klass)
                                    PROP_TABLE_CAPTION,
                                    g_param_spec_string (atk_object_name_property_table_caption,
                                                         "Accessible Table Caption",
-                                                        "Is used to notify that the table caption has changed ",
+                                                        "Is used to notify that the table caption has changed; this property should not be used. accessible-table-caption-object should be used instead",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (gobject_class,
@@ -288,6 +290,13 @@ atk_object_class_init (AtkObjectClass *klass)
                                                         "Is used to notify that the table summary has changed ",
                                                         ATK_TYPE_OBJECT,
                                                         G_PARAM_READWRITE));
+  g_object_class_install_property (gobject_class,
+                                   PROP_TABLE_CAPTION_OBJECT,
+                                   g_param_spec_object (atk_object_name_property_table_caption_object,
+                                                        "Accessible Table Caption Object",
+                                                        "Is used to notify that the table caption has changed ",
+                                                        ATK_TYPE_OBJECT,
+                                                        G_PARAM_READWRITE));
   /*
    * The signal "children_changed" supports two details:
    * "add" and "remove"
diff --git a/atk/atkobject.h b/atk/atkobject.h
index ddef6d8..f9fdaa9 100755
--- a/atk/atkobject.h
+++ b/atk/atkobject.h
@@ -116,7 +116,11 @@ extern "C" {
  *@ATK_ROLE_APPLICATION: The object is an application object, which may contain @ATK_ROLE_FRAME objects or other types of accessibles.
  *@ATK_ROLE_LAST_DEFINED: not a valid role, used for finding end of enumeration
  * 
- *Describes the role of an object
+ * Describes the role of an object
+ *
+ * These are the built-in enumerated roles that UI components can have in
+ * ATK.  Other roles may be added at runtime, so an AtkRole >=
+ * ATK_ROLE_LAST_DEFINED is not necessarily an error.
  **/
 typedef enum
 {
@@ -211,6 +215,10 @@ AtkRole                  atk_role_register        (const gchar *name);
  *@ATK_LAYER_WINDOW: This layer is used for toplevel windows.
  *
  * Describes the layer of a component
+ *
+ * These enumerated "layer values" are used when determining which UI
+ * rendering layer a component is drawn into, which can help in making
+ * determinations of when components occlude one another.
  **/
 typedef enum
 {
diff --git a/atk/atkrelation.c b/atk/atkrelation.c
index be7e4be..a9d5f75 100755
--- a/atk/atkrelation.c
+++ b/atk/atkrelation.c
@@ -23,12 +23,31 @@
 #include "atkrelation.h"
 #include "atk-enum-types.h"
 
+enum {
+  PROP_0,
+
+  PROP_RELATION_TYPE,
+  PROP_TARGET,
+  PROP_LAST
+};
+
 GPtrArray *extra_names = NULL;
 
 static gpointer parent_class = NULL;
   
-static void atk_relation_class_init (AtkRelationClass *klass);
-static void atk_relation_finalize   (GObject          *object);
+static void atk_relation_class_init   (AtkRelationClass *klass);
+static void atk_relation_finalize     (GObject          *object);
+static void atk_relation_set_property (GObject          *object,
+                                       guint            prop_id,
+                                       const GValue     *value,
+                                       GParamSpec       *pspec);
+static void atk_relation_get_property (GObject          *object,
+                                       guint            prop_id,
+                                       GValue           *value,
+                                       GParamSpec       *pspec);
+
+static GPtrArray* atk_relation_get_ptr_array_from_value_array (GValueArray *array);
+static GValueArray* atk_relation_get_value_array_from_ptr_array (GPtrArray *array);
 
 GType
 atk_relation_get_type (void)
@@ -62,6 +81,25 @@ atk_relation_class_init (AtkRelationClass *klass)
   parent_class = g_type_class_peek_parent (klass);
   
   gobject_class->finalize = atk_relation_finalize;
+  gobject_class->set_property = atk_relation_set_property;
+  gobject_class->get_property = atk_relation_get_property;
+
+  g_object_class_install_property (gobject_class,
+                                   PROP_RELATION_TYPE,
+                                   g_param_spec_enum ("relation_type",
+                                                      "Relation Type",
+                                                      "The type of the relation",
+                                                      ATK_TYPE_RELATION_TYPE,
+                                                      ATK_RELATION_NULL,
+                                                      G_PARAM_READWRITE));
+  g_object_class_install_property (gobject_class,
+                                   PROP_TARGET,
+                                   g_param_spec_value_array ("target",
+                                                             "Target",
+                                                             "An array of the targets for the relation",
+                                                             NULL,
+
+                                                             G_PARAM_READWRITE));
 }
 
 /**
@@ -69,7 +107,7 @@ atk_relation_class_init (AtkRelationClass *klass)
  * @name: a name string
  *
  * Associate @name with a new #AtkRelationType
- *
+ 
  * Returns: an #AtkRelationType associated with @name
  **/
 AtkRelationType
@@ -196,23 +234,26 @@ atk_relation_new (AtkObject       **targets,
 {
   AtkRelation *relation;
   int         i;
-  GPtrArray      *array;
+  GValueArray *array;
+  GValue      *value;
 
   g_return_val_if_fail (targets != NULL, NULL);
 
-  relation = g_object_new (ATK_TYPE_RELATION, NULL);
-  array = g_ptr_array_sized_new (n_targets);
+  array = g_value_array_new (n_targets);
   for (i = 0; i < n_targets; i++)
   {
-    /*
-     * Add a reference to AtkObject being added to a relation
-     */
-    g_object_ref (targets[i]);
-    g_ptr_array_add (array, targets[i]);
+    value = g_new0 (GValue, 1);
+    g_value_init (value, ATK_TYPE_OBJECT);
+    g_value_set_object (value, targets[i]);
+    array = g_value_array_append (array, value);
   }
   
-  relation->target = array;
-  relation->relationship = relationship;
+  relation =  g_object_new (ATK_TYPE_RELATION, 
+                            "relation_type", relationship,
+                            "target", array,
+                            NULL);
+
+  g_value_array_free (array);
 
   return relation;
 }
@@ -274,3 +315,92 @@ atk_relation_finalize (GObject *object)
 
   G_OBJECT_CLASS (parent_class)->finalize (object);
 }
+
+static void 
+atk_relation_set_property (GObject       *object,
+                           guint         prop_id,
+                           const GValue  *value,
+                           GParamSpec    *pspec)
+{
+  AtkRelation *relation;
+  gpointer boxed;
+
+  relation = ATK_RELATION (object);
+
+  switch (prop_id)
+    {
+    case PROP_RELATION_TYPE:
+      relation->relationship = g_value_get_enum (value);
+      break; 
+    case PROP_TARGET:
+      boxed = g_value_get_boxed (value);
+      relation->target = atk_relation_get_ptr_array_from_value_array ( (GValueArray *) boxed);
+      break; 
+    default:
+      break;
+    }  
+}
+
+static void
+atk_relation_get_property (GObject    *object,
+                           guint      prop_id,
+                           GValue     *value,
+                           GParamSpec *pspec)
+{
+  AtkRelation *relation;
+  GValueArray *array;
+
+  relation = ATK_RELATION (object);
+
+  switch (prop_id)
+    {
+    case PROP_RELATION_TYPE:
+      g_value_set_enum (value, relation->relationship);
+      break;
+    case PROP_TARGET:
+      array = atk_relation_get_value_array_from_ptr_array (relation->target);
+      g_value_set_boxed (value, array);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+      break;
+    }  
+}
+
+static GPtrArray*
+atk_relation_get_ptr_array_from_value_array (GValueArray *array)
+{
+  gint i;
+  GPtrArray *return_array;
+  GValue *value;
+  GObject *obj;
+
+  return_array = g_ptr_array_sized_new (array->n_values);
+  for (i = 0; i < array->n_values; i++)
+    {
+      value = g_value_array_get_nth (array, i);
+      obj = g_value_get_object (value);
+      g_object_ref (obj);
+      g_ptr_array_add (return_array, obj);
+    }
+      
+  return return_array;
+}
+
+static GValueArray*
+atk_relation_get_value_array_from_ptr_array (GPtrArray *array)
+{
+  int         i;
+  GValueArray *return_array;
+  GValue      *value;
+
+  return_array = g_value_array_new (array->len);
+  for (i = 0; i < array->len; i++)
+    {
+      value = g_new0 (GValue, 1);
+      g_value_init (value, ATK_TYPE_OBJECT);
+      g_value_set_object (value, g_ptr_array_index (array, i));
+      return_array = g_value_array_append (return_array, value);
+    }
+  return return_array;
+}
diff --git a/atk/atktext.c b/atk/atktext.c
index c88eba7..bf2a814 100755
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -66,6 +66,18 @@ static const gchar *underline[] = {"none",
 
 static void atk_text_base_init (gpointer *g_class);
 
+static void atk_text_real_get_range_extents  (AtkText          *text,
+                                              gint             start_offset,
+                                              gint             end_offset,
+                                              AtkCoordType     coord_type,
+                                              AtkTextRectangle *rect);
+
+static AtkTextRange** atk_text_real_get_bounded_ranges (AtkText          *text,
+                                                        AtkTextRectangle *rect,
+                                                        AtkCoordType     coord_type,
+                                                        AtkTextClipType  x_clip_type,
+                                                        AtkTextClipType  y_clip_type);
+
 static guint atk_text_signals[LAST_SIGNAL] = { 0 };
 
 GType
@@ -483,15 +495,15 @@ atk_text_get_caret_offset (AtkText *text)
 /**
  * atk_text_get_character_extents:
  * @text: an #AtkText
- * @offset: position
- * @x: x-position of character
- * @y: y-position of character
- * @width: width of character
- * @height: height of character
+ * @offset: The offset of the text character for which bounding information is required.
+ * @x: Pointer for the x cordinate of the bounding box.
+ * @y: Pointer for the y cordinate of the bounding box.
+ * @width: Pointer for the width of the bounding box
+ * @height: Pointer for the height of the bounding box.
  * @coords: specify whether coordinates are relative to the screen or widget window 
  *
- * Given an @offset, the @x, @y, @width, and @height values are filled
- * appropriately. 
+ * Get the bounding box containing the glyph representing the character at 
+ *     a particular text offset. 
  **/
 void
 atk_text_get_character_extents (AtkText *text,
@@ -537,6 +549,12 @@ atk_text_get_character_extents (AtkText *text,
 
   if (iface->get_character_extents)
     (*(iface->get_character_extents)) (text, offset, real_x, real_y, real_width, real_height, coords);
+
+  if (*real_width <0)
+    {
+      *real_x = *real_x + *real_width;
+      *real_width *= -1;
+    }
 }
 
 /**
@@ -865,6 +883,74 @@ atk_text_set_caret_offset (AtkText *text,
 }
 
 /**
+ * atk_text_get_range_extents:
+ * @text: an #AtkText
+ * @start_offset: The offset of the first text character for which boundary 
+ *        information is required.
+ * @end_offset: The offset of the text character after the last character 
+ *        for which boundary information is required.
+ * @coord_type: Specify whether coordinates are relative to the screen or widget window.
+ * @rect: A pointer to a AtkTextRectangle which is filled in by this function.
+ *
+ * Get the bounding box for text within the specified range.
+ **/
+void
+atk_text_get_range_extents (AtkText          *text,
+                            gint             start_offset,
+                            gint             end_offset,
+                            AtkCoordType     coord_type,
+                            AtkTextRectangle *rect)
+{
+  AtkTextIface *iface;
+
+  g_return_if_fail (ATK_IS_TEXT (text));
+  g_return_if_fail (rect);
+
+  if (start_offset < 0 || start_offset >= end_offset)
+    return;
+ 
+  iface = ATK_TEXT_GET_IFACE (text);
+
+  if (iface->get_range_extents)
+    (*(iface->get_range_extents)) (text, start_offset, end_offset, coord_type, rect);
+  else
+    atk_text_real_get_range_extents (text, start_offset, end_offset, coord_type, rect);
+}
+
+/**
+ * atk_text_get_bounded_ranges:
+ * @text: an #AtkText
+ * @rect: An AtkTextRectagle giving the dimensions of the bounding box.
+ * @coord_type: Specify whether coordinates are relative to the screen or widget window.
+ * @x_clip_type: Specify the horizontal clip type.
+ * @y_clip_type: Specify the vertical clip type.
+ *
+ * Get the ranges of text in the specified bounding box.
+ *
+ * Returns: Array of AtkTextRange. The last element of the array returned 
+ *          by this function will be NULL.
+ **/
+AtkTextRange**
+atk_text_get_bounded_ranges (AtkText          *text,
+                             AtkTextRectangle *rect,
+                             AtkCoordType      coord_type,
+                             AtkTextClipType   x_clip_type,
+                             AtkTextClipType   y_clip_type)
+{
+  AtkTextIface *iface;
+
+  g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
+  g_return_val_if_fail (rect, NULL);
+
+  iface = ATK_TEXT_GET_IFACE (text);
+
+  if (iface->get_bounded_ranges)
+    return (*(iface->get_bounded_ranges)) (text, rect, coord_type, x_clip_type, y_clip_type);
+  else
+    return atk_text_real_get_bounded_ranges (text, rect, coord_type, x_clip_type, y_clip_type);
+}
+
+/**
  * atk_attribute_set_free:
  * @attrib_set: The #AtkAttributeSet to free
  *
@@ -1006,7 +1092,6 @@ atk_text_attribute_for_name (const gchar *name)
   return type;
 }
 
-
 /**
  * atk_text_attribute_get_value:
  * @attr: The #AtkTextAttribute for which a value is required
@@ -1056,3 +1141,182 @@ atk_text_attribute_get_value (AtkTextAttribute attr,
       return NULL;
    }
 }
+
+static void
+atk_text_rectangle_union (AtkTextRectangle *src1,
+                          AtkTextRectangle *src2,
+                          AtkTextRectangle *dest)
+{
+  gint dest_x, dest_y;
+
+  dest_x = MIN (src1->x, src2->x);
+  dest_y = MIN (src1->y, src2->y);
+  dest->width = MAX (src1->x + src1->width, src2->x + src2->width) - dest_x;
+  dest->height = MAX (src1->y + src1->height, src2->y + src2->height) - dest_y;
+  dest->x = dest_x;
+  dest->y = dest_y;
+}
+
+static gboolean
+atk_text_rectangle_contain (AtkTextRectangle *clip,
+                            AtkTextRectangle *bounds,
+                            AtkTextClipType  x_clip_type,
+                            AtkTextClipType  y_clip_type)
+{
+  gboolean x_min_ok, x_max_ok, y_min_ok, y_max_ok;
+
+  x_min_ok = (bounds->x >= clip->x) ||
+             ((bounds->x + bounds->width >= clip->x) &&
+              ((x_clip_type == ATK_TEXT_CLIP_NONE) ||
+               (x_clip_type == ATK_TEXT_CLIP_MAX)));
+
+  x_max_ok = (bounds->x + bounds->width <= clip->x + clip->width) ||
+             ((bounds->x <= clip->x + clip->width) &&
+              ((x_clip_type == ATK_TEXT_CLIP_NONE) ||
+               (x_clip_type == ATK_TEXT_CLIP_MIN)));
+
+  y_min_ok = (bounds->y >= clip->y) ||
+             ((bounds->y + bounds->height >= clip->y) &&
+              ((y_clip_type == ATK_TEXT_CLIP_NONE) ||
+               (y_clip_type == ATK_TEXT_CLIP_MAX)));
+
+  y_max_ok = (bounds->y + bounds->height <= clip->y + clip->height) ||
+             ((bounds->y <= clip->y + clip->height) &&
+              ((y_clip_type == ATK_TEXT_CLIP_NONE) ||
+               (y_clip_type == ATK_TEXT_CLIP_MIN)));
+
+  return (x_min_ok && x_max_ok && y_min_ok && y_max_ok);
+  
+}
+
+static void 
+atk_text_real_get_range_extents (AtkText           *text,
+                                 gint              start_offset,
+                                 gint              end_offset,
+                                 AtkCoordType      coord_type,
+                                 AtkTextRectangle  *rect)
+{
+  gint i;
+  AtkTextRectangle cbounds, bounds;
+
+  atk_text_get_character_extents (text, start_offset,
+                                  &bounds.x, &bounds.y,
+                                  &bounds.width, &bounds.height,
+                                  coord_type);
+
+  for (i = start_offset + 1; i < end_offset; i++)
+    {
+      atk_text_get_character_extents (text, i,
+                                      &cbounds.x, &cbounds.y, 
+                                      &cbounds.width, &cbounds.height, 
+                                      coord_type);
+      atk_text_rectangle_union (&bounds, &cbounds, &bounds);
+    }
+
+  rect->x = bounds.x;
+  rect->y = bounds.y;
+  rect->width = bounds.width;
+  rect->height = bounds.height;
+}
+
+static AtkTextRange**
+atk_text_real_get_bounded_ranges (AtkText          *text,
+                                  AtkTextRectangle *rect,
+                                  AtkCoordType     coord_type,
+                                  AtkTextClipType  x_clip_type,
+                                  AtkTextClipType  y_clip_type)
+{
+  gint bounds_min_offset, bounds_max_offset;
+  gint min_line_start, min_line_end;
+  gint max_line_start, max_line_end;
+  gchar *line;
+  gint curr_offset;
+  gint offset;
+  gint num_ranges = 0;
+  gint range_size = 1;
+  AtkTextRectangle cbounds;
+  AtkTextRange **range;
+
+  range = NULL;
+  bounds_min_offset = atk_text_get_offset_at_point (text, rect->x, rect->y, coord_type);
+  bounds_max_offset = atk_text_get_offset_at_point (text, rect->x + rect->width, rect->y + rect->height, coord_type);
+
+  if (bounds_min_offset == 0 &&
+      bounds_min_offset == bounds_max_offset)
+    return NULL;
+
+  line = atk_text_get_text_at_offset (text, bounds_min_offset, 
+                                      ATK_TEXT_BOUNDARY_LINE_START,
+                                      &min_line_start, &min_line_end);
+  g_free (line);
+  line = atk_text_get_text_at_offset (text, bounds_max_offset, 
+                                      ATK_TEXT_BOUNDARY_LINE_START,
+                                      &max_line_start, &max_line_end);
+  g_free (line);
+  bounds_min_offset = MIN (min_line_start, max_line_start);
+  bounds_max_offset = MAX (min_line_end, max_line_end);
+
+  curr_offset = bounds_min_offset;
+  while (curr_offset < bounds_max_offset)
+    {
+      offset = curr_offset;
+
+      while (curr_offset < bounds_max_offset)
+        {
+          atk_text_get_character_extents (text, curr_offset,
+                                          &cbounds.x, &cbounds.y,
+                                          &cbounds.width, &cbounds.height,
+                                          coord_type);
+          if (!atk_text_rectangle_contain (rect, &cbounds, x_clip_type, y_clip_type))
+	    break;
+          curr_offset++;
+        }
+      if (curr_offset > offset)
+        {
+          AtkTextRange *one_range = g_new (AtkTextRange, 1);
+
+          one_range->start_offset = offset;
+          one_range->end_offset = curr_offset;
+          one_range->content = atk_text_get_text (text, offset, curr_offset);
+          atk_text_get_range_extents (text, offset, curr_offset, coord_type, &one_range->bounds);
+
+          if (num_ranges >= range_size - 1)
+            {
+              range_size *= 2;
+              range = g_realloc (range, range_size * sizeof (gpointer));
+            }
+          range[num_ranges] = one_range;
+          num_ranges++; 
+        }   
+      curr_offset++;
+      if (range)
+        range[num_ranges] = NULL;
+    }
+  return range;
+}
+
+/**
+ * atk_text_free_ranges:
+ * @ranges: A pointer to an array of  #AtkTextRange which is to be freed.
+ *
+ * Frees the memory associated with an array of AtkTextRange. It is assumed
+ * that the array was returned by the function atk_text_get_bounded_ranges
+ * and is NULL terminated.
+ **/
+void
+atk_text_free_ranges (AtkTextRange **ranges)
+{
+  if (ranges)
+    {
+      while (*ranges)
+        {
+          AtkTextRange *range;
+
+          range = *ranges;
+          *ranges++;
+          g_free (range->content);
+          g_free (ranges);
+        }
+      g_free (ranges);
+    }
+}
diff --git a/atk/atktext.h b/atk/atktext.h
index 8ec3469..1d3b2bc 100755
--- a/atk/atktext.h
+++ b/atk/atktext.h
@@ -158,6 +158,59 @@ typedef enum {
   ATK_TEXT_BOUNDARY_LINE_END
 } AtkTextBoundary;
 
+/**
+ * AtkTextRectangle:
+ * @x: The horizontal coordinate of a rectangle
+ * @y: The vertical coordinate of a rectangle
+ * @width: The width of a rectangle
+ * @height: The height of a rectangle
+ *
+ * A structure used to store a rectangle used by AtkText.
+ **/
+
+typedef struct _AtkTextRectangle AtkTextRectangle;
+
+struct _AtkTextRectangle {
+  gint x;
+  gint y;
+  gint width;
+  gint height;
+};
+
+/**
+ * AtkTextRange:
+ * @bounds: A rectangle giving the bounds of the text range
+ * @start_offset: The start offset of a AtkTextRange
+ * @end_offset: The end offset of a AtkTextRange
+ * @content: The text in the text range
+ *
+ * A structure used to describe a text range.
+ **/
+typedef struct _AtkTextRange AtkTextRange;
+
+struct _AtkTextRange {
+  AtkTextRectangle bounds;
+  gint start_offset;
+  gint end_offset;
+  gchar* content;
+};
+
+/**
+ *AtkTextClipType
+ *@ATK_TEXT_CLIP_NONE: No clipping to be done
+ *@ATK_TEXT_CLIP_MIN: Text clipped by min coordinate is omitted
+ *@ATK_TEXT_CLIP_MAX: Text clipped by max coordinate is omitted
+ *@ATK_TEXT_CLIP_BOTH: Only text fully within mix/max bound is retained
+ *
+ *Describes the type of clipping required.
+ **/
+typedef enum {
+    ATK_TEXT_CLIP_NONE,
+    ATK_TEXT_CLIP_MIN,
+    ATK_TEXT_CLIP_MAX,
+    ATK_TEXT_CLIP_BOTH
+} AtkTextClipType;
+
 struct _AtkTextIface
 {
   GTypeInterface parent;
@@ -229,8 +282,20 @@ struct _AtkTextIface
 
   void           (* text_attributes_changed)      (AtkText          *text);
 
-  AtkFunction    pad2;
-  AtkFunction    pad3;
+
+  void           (* get_range_extents)            (AtkText          *text,
+                                                   gint             start_offset,
+                                                   gint             end_offset,
+                                                   AtkCoordType     coord_type,
+                                                   AtkTextRectangle *rect);
+
+  AtkTextRange** (* get_bounded_ranges)           (AtkText          *text,
+                                                   AtkTextRectangle *rect,
+                                                   AtkCoordType     coord_type,
+                                                   AtkTextClipType  x_clip_type,
+                                                   AtkTextClipType  y_clip_type);
+ 
+
   AtkFunction    pad4;
 };
 
@@ -298,6 +363,18 @@ gboolean      atk_text_set_selection                      (AtkText          *tex
 							   gint             end_offset);
 gboolean      atk_text_set_caret_offset                   (AtkText          *text,
                                                            gint             offset);
+void          atk_text_get_range_extents                  (AtkText          *text,
+
+                                                           gint             start_offset,
+                                                           gint             end_offset,
+                                                           AtkCoordType     coord_type,
+                                                           AtkTextRectangle *rect);
+AtkTextRange**  atk_text_get_bounded_ranges               (AtkText          *text,
+                                                           AtkTextRectangle *rect,
+                                                           AtkCoordType     coord_type,
+                                                           AtkTextClipType  x_clip_type,
+                                                           AtkTextClipType  y_clip_type);
+void          atk_text_free_ranges                        (AtkTextRange     **ranges);
 void 	      atk_attribute_set_free                      (AtkAttributeSet  *attrib_set);
 G_CONST_RETURN gchar*  atk_text_attribute_get_name        (AtkTextAttribute attr);
 AtkTextAttribute       atk_text_attribute_for_name        (const gchar      *name);
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index 47ba1a2..2929091 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -370,6 +370,9 @@ atk_table_get_type
 <TITLE>AtkText</TITLE>
 AtkText
 AtkTextBoundary
+AtkTextClipType
+AtkTextRange
+AtkTextRectangle
 AtkAttribute
 AtkAttributeSet
 AtkTextAttribute
@@ -384,6 +387,9 @@ atk_text_get_run_attributes
 atk_text_get_default_attributes
 atk_text_get_character_count
 atk_text_get_offset_at_point
+atk_text_get_bounded_ranges
+atk_text_get_range_extents
+atk_text_free_ranges
 atk_text_get_n_selections
 atk_text_get_selection
 atk_text_add_selection
@@ -403,9 +409,11 @@ ATK_TYPE_TEXT
 ATK_TEXT_GET_IFACE
 ATK_TYPE_TEXT_ATTRIBUTE
 ATK_TYPE_TEXT_BOUNDARY
+ATK_TYPE_TEXT_CLIP_TYPE
 atk_text_get_type
 atk_text_attribute_get_type
 atk_text_boundary_get_type
+atk_text_clip_type_get_type
 </SECTION>
 
 <SECTION>
diff --git a/docs/tmpl/atkobject.sgml b/docs/tmpl/atkobject.sgml
index 223fea7..1dee081 100644
--- a/docs/tmpl/atkobject.sgml
+++ b/docs/tmpl/atkobject.sgml
@@ -40,9 +40,6 @@ The AtkObject structure should not be accessed directly.
 
 <!-- ##### ENUM AtkRole ##### -->
 <para>
-These are the built-in enumerated roles that UI components can have in
-ATK.  Other roles may be added at runtime, so an AtkRole >=
-ATK_ROLE_LAST_DEFINED is not necessarily an error.
 </para>
 
 @ATK_ROLE_INVALID: 
@@ -132,9 +129,6 @@ ATK_ROLE_LAST_DEFINED is not necessarily an error.
 
 <!-- ##### ENUM AtkLayer ##### -->
 <para>
-These enumerated "layer values" are used when determining which UI
-rendering layer a component is drawn into, which can help in making
-determinations of when components occlude one another.
 </para>
 
 @ATK_LAYER_INVALID: 
@@ -509,6 +503,11 @@ This signal support, which may be any of the accessible state types.
 
 </para>
 
+<!-- ##### ARG AtkObject:accessible-table-caption-object ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG AtkObject:accessible-table-column-description ##### -->
 <para>
 
diff --git a/docs/tmpl/atkrelation.sgml b/docs/tmpl/atkrelation.sgml
index a6c258c..e525303 100644
--- a/docs/tmpl/atkrelation.sgml
+++ b/docs/tmpl/atkrelation.sgml
@@ -101,3 +101,13 @@ The AtkRelation structure should not be accessed directly.
 @Returns: 
 
 
+<!-- ##### ARG AtkRelation:relation-type ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG AtkRelation:target ##### -->
+<para>
+
+</para>
+
diff --git a/docs/tmpl/atktext.sgml b/docs/tmpl/atktext.sgml
index 89494eb..4910972 100644
--- a/docs/tmpl/atktext.sgml
+++ b/docs/tmpl/atktext.sgml
@@ -51,6 +51,36 @@ The AtkText structure does not contain any fields.
 @ATK_TEXT_BOUNDARY_LINE_START: 
 @ATK_TEXT_BOUNDARY_LINE_END: 
 
+<!-- ##### ENUM AtkTextClipType ##### -->
+<para>
+
+</para>
+
+@ATK_TEXT_CLIP_NONE: 
+@ATK_TEXT_CLIP_MIN: 
+@ATK_TEXT_CLIP_MAX: 
+@ATK_TEXT_CLIP_BOTH: 
+
+<!-- ##### STRUCT AtkTextRange ##### -->
+<para>
+
+</para>
+
+@bounds: 
+@start_offset: 
+@end_offset: 
+@content: 
+
+<!-- ##### STRUCT AtkTextRectangle ##### -->
+<para>
+
+</para>
+
+@x: 
+@y: 
+@width: 
+@height: 
+
 <!-- ##### STRUCT AtkAttribute ##### -->
 <para>
 
@@ -225,6 +255,39 @@ The AtkText structure does not contain any fields.
 @Returns: 
 
 
+<!-- ##### FUNCTION atk_text_get_bounded_ranges ##### -->
+<para>
+
+</para>
+
+@text: 
+@rect: 
+@coord_type: 
+@x_clip_type: 
+@y_clip_type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION atk_text_get_range_extents ##### -->
+<para>
+
+</para>
+
+@text: 
+@start_offset: 
+@end_offset: 
+@coord_type: 
+@rect: 
+
+
+<!-- ##### FUNCTION atk_text_free_ranges ##### -->
+<para>
+
+</para>
+
+@ranges: 
+
+
 <!-- ##### FUNCTION atk_text_get_n_selections ##### -->
 <para>