[atk] Implement atk_text_get_string_at_offset() and deprecate old API

[Mario Sanchez Prada <msanchez src gnome org>]

commit 3261a8a792f6688b5575512b8828eea262164713
Author: Mario Sanchez Prada <mario prada samsung com>
Date:   Fri Aug 9 18:11:53 2013 +0100

    Implement atk_text_get_string_at_offset() and deprecate old API
    
    https://bugzilla.gnome.org/show_bug.cgi?id=705580

 atk/atk.symbols       |    2 +
 atk/atktext.c         |   86 +++++++++++++++++++++++++++++++++++++++++++++++++
 atk/atktext.h         |   63 +++++++++++++++++++++++++++++------
 docs/atk-sections.txt |    4 ++
 4 files changed, 144 insertions(+), 11 deletions(-)
---
diff --git a/atk/atk.symbols b/atk/atk.symbols
index 052dc5a..00f1dba 100644
--- a/atk/atk.symbols
+++ b/atk/atk.symbols
@@ -220,6 +220,7 @@
        atk_text_attribute_get_value
        atk_text_attribute_register
        atk_text_boundary_get_type
+       atk_text_granularity_get_type
        atk_text_clip_type_get_type
        atk_text_free_ranges
        atk_text_get_bounded_ranges
@@ -237,6 +238,7 @@
        atk_text_get_text_after_offset
        atk_text_get_text_at_offset
        atk_text_get_text_before_offset
+       atk_text_get_string_at_offset
        atk_text_get_type
        atk_text_range_get_type
        atk_text_remove_selection
diff --git a/atk/atktext.c b/atk/atktext.c
index 37f6a6b..5bea401 100755
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -557,6 +557,92 @@ atk_text_get_text_before_offset (AtkText          *text,
 }
 
 /**
+ * atk_text_get_string_at_offset:
+ * @text: an #AtkText
+ * @offset: position
+ * @granularity: An #AtkTextGranularity
+ * @start_offset: (out): the start offset of the returned string, or -1
+ *                if an error has occurred (e.g. invalid offset, not implemented)
+ * @end_offset: (out): the offset of the first character after the returned string,
+ *              or -1 if an error has occurred (e.g. invalid offset, not implemented)
+ *
+ * Gets a portion of the text exposed through an #AtkText according to a given @offset
+ * and a specific @granularity, along with the start and end offsets defining the
+ * boundaries of such a portion of text.
+ *
+ * If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the
+ * offset is returned.
+ *
+ * If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string
+ * is from the word start at or before the offset to the word start after
+ * the offset.
+ *
+ * The returned string will contain the word at the offset if the offset
+ * is inside a word and will contain the word before the offset if the
+ * offset is not inside a word.
+ *
+ * If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string
+ * is from the sentence start at or before the offset to the sentence
+ * start after the offset.
+ *
+ * The returned string will contain the sentence at the offset if the offset
+ * is inside a sentence and will contain the sentence before the offset
+ * if the offset is not inside a sentence.
+ *
+ * If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string
+ * is from the line start at or before the offset to the line
+ * start after the offset.
+ *
+ * If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string
+ * is from the start of the paragraph at or before the offset to the start
+ * of the following paragraph after the offset.
+ *
+ * Since: 2.9.4
+ *
+ * Returns: a newly allocated string containing the text at the @offset bounded
+ *   by the specified @granularity. Use g_free() to free the returned string.
+ *   Returns %NULL if the offset is invalid or no implementation is available.
+ **/
+gchar* atk_text_get_string_at_offset (AtkText *text,
+                                      gint offset,
+                                      AtkTextGranularity granularity,
+                                      gint *start_offset,
+                                      gint *end_offset)
+{
+  AtkTextIface *iface;
+  gint local_start_offset, local_end_offset;
+  gint *real_start_offset, *real_end_offset;
+
+  g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
+
+  if (start_offset)
+    {
+      *start_offset = -1;
+      real_start_offset = start_offset;
+    }
+  else
+    real_start_offset = &local_start_offset;
+
+  if (end_offset)
+    {
+      *end_offset = -1;
+      real_end_offset = end_offset;
+    }
+  else
+    real_end_offset = &local_end_offset;
+
+  if (offset < 0)
+    return NULL;
+
+  iface = ATK_TEXT_GET_IFACE (text);
+
+  if (iface->get_string_at_offset)
+    return (*(iface->get_string_at_offset)) (text, offset, granularity, real_start_offset, real_end_offset);
+  else
+    return NULL;
+}
+
+/**
  * atk_text_get_caret_offset:
  * @text: an #AtkText
  *
diff --git a/atk/atktext.h b/atk/atktext.h
index 759eb5f..96bd28b 100755
--- a/atk/atktext.h
+++ b/atk/atktext.h
@@ -118,25 +118,20 @@ typedef struct _AtkTextIface AtkTextIface;
  * (including non-printing characters)
  * ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word.
  * ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last
- * character) of a word. This boundary is deprecated, and should not be
- * used.
+ * character) of a word.
  * ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence.
  * ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal)
  * character in a sentence; in languages which use "sentence stop"
  * punctuation such as English, the boundary is thus the '.', '?', or
- * similar terminal punctuation character. This boundary is
- * deprecated, and should not be used.
+ * similar terminal punctuation character.
  * ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a
  * character immediately following a newline, linefeed, or return character.
  * ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return
- * character. This boundary is deprecated, and should not be used.
- *
- * Text boundary types used for specifying boundaries for regions of
- * text. Note that some boundaries are deprecated since 2.9.3., not
- * marked explicitly due to the lack of a formal method to mark as
- * deprecated some elements from a enum.
- *
+ * character.
  *
+ * Text boundary types used for specifying boundaries for regions of text.
+ * This enumerationis deprecated since 2.9.4 and should not be used. Use
+ * AtkTextGranularity with #atk_text_get_string_at_offset instead.
  **/
 typedef enum {
   ATK_TEXT_BOUNDARY_CHAR,
@@ -149,6 +144,34 @@ typedef enum {
 } AtkTextBoundary;
 
 /**
+ *AtkTextGranularity:
+ * ATK_TEXT_GRANULARITY_CHAR: Granularity is defined by the boundaries between characters
+ * (including non-printing characters)
+ * ATK_TEXT_GRANULARITY_WORD: Granularity is defined by the boundaries of a word,
+ * starting at the beginning of the current word and finishing at the beginning of
+ * the following one, if present.
+ * ATK_TEXT_GRANULARITY_SENTENCE: Granularity is defined by the boundaries of a sentence,
+ * starting at the beginning of the current sentence and finishing at the beginning of
+ * the following one, if present.
+ * ATK_TEXT_GRANULARITY_LINE: Granularity is defined by the boundaries of a line,
+ * starting at the beginning of the current line and finishing at the beginning of
+ * the following one, if present.
+ * ATK_TEXT_GRANULARITY_PARAGRAPH: Granularity is defined by the boundaries of a paragraph,
+ * starting at the beginning of the current paragraph and finishing at the beginning of
+ * the following one, if present.
+ *
+ * Text granularity types used for specifying the granularity of the region of
+ * text we are interested in.
+ **/
+typedef enum {
+  ATK_TEXT_GRANULARITY_CHAR,
+  ATK_TEXT_GRANULARITY_WORD,
+  ATK_TEXT_GRANULARITY_SENTENCE,
+  ATK_TEXT_GRANULARITY_LINE,
+  ATK_TEXT_GRANULARITY_PARAGRAPH
+} AtkTextGranularity;
+
+/**
  * AtkTextRectangle:
  * @x: The horizontal coordinate of a rectangle
  * @y: The vertical coordinate of a rectangle
@@ -207,8 +230,14 @@ typedef enum {
  * AtkTextIface:
  * @get_text_after_offset: Gets specified text. This virtual function
  *   is deprecated and it should not be overridden.
+ * @get_text_at_offset: Gets specified text. This virtual function
+ *   is deprecated and it should not be overridden.
  * @get_text_before_offset: Gets specified text. This virtual function
  *   is deprecated and it should not be overridden.
+ * @get_string_at_offset: Gets a portion of the text exposed through
+ *   an AtkText according to a given offset and a specific
+ *   granularity, along with the start and end offsets defining the
+ *   boundaries of such a portion of text.
  * @text_changed: the signal handler which is executed when there is a
  *   text change. This virtual function is deprecated sice 2.9.4 and
  *   it should not be overriden.
@@ -296,6 +325,12 @@ struct _AtkTextIface
                                                    AtkCoordType     coord_type,
                                                    AtkTextClipType  x_clip_type,
                                                    AtkTextClipType  y_clip_type);
+
+  gchar*         (* get_string_at_offset)         (AtkText            *text,
+                                                   gint               offset,
+                                                   AtkTextGranularity granularity,
+                                                   gint               *start_offset,
+                                                   gint               *end_offset);
 };
 
 GType            atk_text_get_type (void);
@@ -319,6 +354,7 @@ gchar*        atk_text_get_text_after_offset              (AtkText          *tex
                                                            AtkTextBoundary  boundary_type,
                                                           gint             *start_offset,
                                                           gint             *end_offset);
+G_DEPRECATED_FOR(atk_text_get_text_at_offset)
 gchar*        atk_text_get_text_at_offset                 (AtkText          *text,
                                                            gint             offset,
                                                            AtkTextBoundary  boundary_type,
@@ -330,6 +366,11 @@ gchar*        atk_text_get_text_before_offset             (AtkText          *tex
                                                            AtkTextBoundary  boundary_type,
                                                           gint             *start_offset,
                                                           gint             *end_offset);
+gchar*        atk_text_get_string_at_offset               (AtkText            *text,
+                                                           gint               offset,
+                                                           AtkTextGranularity granularity,
+                                                           gint               *start_offset,
+                                                           gint               *end_offset);
 gint          atk_text_get_caret_offset                   (AtkText          *text);
 void          atk_text_get_character_extents              (AtkText          *text,
                                                            gint             offset,
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index e50f673..79e7c1f 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -394,6 +394,7 @@ atk_table_get_type
 AtkText
 AtkTextIface
 AtkTextBoundary
+AtkTextGranularity
 AtkTextClipType
 AtkTextRange
 AtkTextRectangle
@@ -405,6 +406,7 @@ atk_text_get_character_at_offset
 atk_text_get_text_after_offset
 atk_text_get_text_at_offset
 atk_text_get_text_before_offset
+atk_text_get_string_at_offset
 atk_text_get_caret_offset
 atk_text_get_character_extents
 atk_text_get_run_attributes
@@ -432,10 +434,12 @@ ATK_TYPE_TEXT
 ATK_TEXT_GET_IFACE
 ATK_TYPE_TEXT_ATTRIBUTE
 ATK_TYPE_TEXT_BOUNDARY
+ATK_TYPE_TEXT_GRANULARITY
 ATK_TYPE_TEXT_CLIP_TYPE
 atk_text_get_type
 atk_text_attribute_get_type
 atk_text_boundary_get_type
+atk_text_granularity_get_type
 atk_text_clip_type_get_type
 </SECTION>