[at-spi2-core] Add atspi_text_get_string_at_offset

[Mike Gorse <mgorse src gnome org>]

commit 56220f05bc8b7683911658e1a8aff4a1ab3cab8d
Author: Mike Gorse <mgorse suse com>
Date:   Mon Aug 19 16:43:02 2013 -0500

    Add atspi_text_get_string_at_offset

 atspi/atspi-constants.h |   30 ++++++++++++++++++
 atspi/atspi-text.c      |   76 +++++++++++++++++++++++++++++++++++++++++++++++
 atspi/atspi-text.h      |    4 ++
 xml/Text.xml            |    8 +++++
 4 files changed, 118 insertions(+), 0 deletions(-)
---
diff --git a/atspi/atspi-constants.h b/atspi/atspi-constants.h
index fe73438..4eb517e 100644
--- a/atspi/atspi-constants.h
+++ b/atspi/atspi-constants.h
@@ -331,6 +331,8 @@ typedef enum {
  * #atspi_text_get_text_at_offset, #atspi_text_get_text_after_offset, and
  * #atspi_text_get_text_before_offset.
  *
+ * This enumerationis deprecated since 2.9.90 and should not be used. Use
+ * AtspiTextGranularity with #atspi_text_get_string_at_offset instead.
  **/
 typedef enum {
     ATSPI_TEXT_BOUNDARY_CHAR,
@@ -343,6 +345,34 @@ typedef enum {
 } AtspiTextBoundaryType;
 
 /**
+ *AtspiTextGranularity:
+ * ATSPI_TEXT_GRANULARITY_CHAR: Granularity is defined by the boundaries between characters
+ * (including non-printing characters)
+ * ATSPI_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.
+ * ATSPI_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.
+ * ATSPI_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.
+ * ATSPI_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 {
+  ATSPI_TEXT_GRANULARITY_CHAR,
+  ATSPI_TEXT_GRANULARITY_WORD,
+  ATSPI_TEXT_GRANULARITY_SENTENCE,
+  ATSPI_TEXT_GRANULARITY_LINE,
+  ATSPI_TEXT_GRANULARITY_PARAGRAPH
+} AtspiTextGranularity;
+
+/**
  * ATSPI_TEXT_BOUNDARY_TYPE_COUNT:
  *
  * One higher than the highest valid value of #AtspiTextBoundaryType.
diff --git a/atspi/atspi-text.c b/atspi/atspi-text.c
index 244000d..e84883e 100644
--- a/atspi/atspi-text.c
+++ b/atspi/atspi-text.c
@@ -422,6 +422,80 @@ atspi_text_get_text_before_offset (AtspiText *obj,
 }
 
 /**
+ * atspi_text_get_string_at_offset:
+ * @text: an #AtspiText
+ * @offset: position
+ * @granularity: An #AtspiTextGranularity
+ * @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 #AtspiText 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 ATSPI_TEXT_GRANULARITY_CHAR the character at the
+ * offset is returned.
+ *
+ * If @granularity is ATSPI_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 ATSPI_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 ATSPI_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 ATSPI_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.90
+ *
+ * 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.
+ **/
+AtspiTextRange *
+atspi_text_get_string_at_offset (AtspiText *obj,
+                                 gint offset,
+                                 AtspiTextGranularity granularity,
+                                 GError **error)
+{
+  dbus_int32_t d_offset = offset;
+  dbus_uint32_t d_granularity = granularity;
+  dbus_int32_t d_start_offset = -1, d_end_offset = -1;
+  AtspiTextRange *range = g_new0 (AtspiTextRange, 1);
+
+  range->start_offset = range->end_offset = -1;
+  if (!obj)
+    return range;
+
+  _atspi_dbus_call (obj, atspi_interface_text, "GetStringAtOffset", error,
+                    "iu=>sii", d_offset, d_granularity, &range->content,
+                    &d_start_offset, &d_end_offset);
+
+  range->start_offset = d_start_offset;
+  range->end_offset = d_end_offset;
+  if (!range->content)
+    range->content = g_strdup ("");
+
+  return range;
+}
+
+/**
  * atspi_text_get_text_at_offset:
  * @obj: a pointer to the #AtspiText object on which to operate.
  * @offset: a #gint indicating the offset from which the delimiter
@@ -435,6 +509,8 @@ atspi_text_get_text_before_offset (AtspiText *obj,
  * Returns: an #AtspiTextRange containing a UTF-8 string representing the
  *          delimited text, whose delimiting boundaries bracket the
  *          current offset, or an empty string if no such text exists.
+ *
+ * Deprecated: 2.10: Use atspi_text_get_string_at_offset.
  **/
 AtspiTextRange *
 atspi_text_get_text_at_offset (AtspiText *obj,
diff --git a/atspi/atspi-text.h b/atspi/atspi-text.h
index f027e9a..a73ea16 100644
--- a/atspi/atspi-text.h
+++ b/atspi/atspi-text.h
@@ -109,7 +109,11 @@ gboolean atspi_text_set_caret_offset (AtspiText *obj, gint new_offset, GError **
 
 AtspiTextRange * atspi_text_get_text_before_offset (AtspiText *obj, gint offset, AtspiTextBoundaryType type, 
GError **error);
 
+AtspiTextRange * atspi_text_get_string_at_offset (AtspiText *obj, gint offset, AtspiTextGranularity 
granularity, GError **error);
+
+#ifndef ATSPI_DISABLE_DEPRECATED
 AtspiTextRange * atspi_text_get_text_at_offset (AtspiText *obj, gint offset, AtspiTextBoundaryType type, 
GError **error);
+#endif
 
 AtspiTextRange * atspi_text_get_text_after_offset (AtspiText *obj, gint offset, AtspiTextBoundaryType type, 
GError **error);
 
diff --git a/xml/Text.xml b/xml/Text.xml
index dd8dd96..7af366a 100644
--- a/xml/Text.xml
+++ b/xml/Text.xml
@@ -6,6 +6,14 @@
 
   <property name="CaretOffset" type="i" access="read"/>
 
+  <method name="GetStringAtOffset">
+    <arg direction="in" name="offset" type="i"/>
+    <arg direction="in" name="granularity" type="u"/>
+    <arg direction="out" type="s"/>
+    <arg direction="out" name="startOffset" type="i"/>
+    <arg direction="out" name="endOffset" type="i"/>
+  </method>
+
   <method name="GetText">
     <arg direction="in" name="startOffset" type="i"/>
     <arg direction="in" name="endOffset" type="i"/>