Revert "Revert "Merge remote-tracking branch 'origin/sandbox/mniesluchow/upstream_2_1...

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

diff --git a/atk/atktext.c b/atk/atktext.c
index d55f5de..f18e8cb 100755 (executable)
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -17,9 +17,10 @@
  * Boston, MA 02111-1307, USA.
  */
 
-#include "atktext.h"
+#include "config.h"
+
+#include "atk.h"
 #include "atkmarshal.h"
-#include "atk-enum-types.h"
 
 #include <string.h>
 
@@ -200,7 +201,7 @@ atk_text_base_init (AtkTextIface *class)
        * "delete" which identifies whether the text change was an
        * insertion or a deletion.
        *
-       * Deprecated: Since 2.9.4. Use #AtkObject::text-insert or
+       * Deprecated: 2.9.4: Use #AtkObject::text-insert or
        * #AtkObject::text-remove instead.
        */
       atk_text_signals[TEXT_CHANGED] =
@@ -221,7 +222,9 @@ atk_text_base_init (AtkTextIface *class)
        * @arg3: The new text inserted
        *
        * The "text-insert" signal is emitted when a new text is
-       * inserted.
+       * inserted. If the signal was not triggered by the user
+       * (e.g. typing or pasting text), the "system" detail should be
+       * included.
        */
       atk_text_signals[TEXT_INSERT] =
        g_signal_new ("text_insert",
@@ -241,7 +244,9 @@ atk_text_base_init (AtkTextIface *class)
        * @arg3: The old text removed
        *
        * The "text-remove" signal is emitted when a new text is
-       * removed.
+       * removed. If the signal was not triggered by the user
+       * (e.g. typing or pasting text), the "system" detail should be
+       * included.
        */
       atk_text_signals[TEXT_REMOVE] =
        g_signal_new ("text_remove",
@@ -377,8 +382,7 @@ atk_text_get_character_at_offset (AtkText      *text,
  *
  * Gets the specified text.
  *
- * Deprecated: This method is deprecated since ATK version
- * 2.9.3. Please use atk_text_get_string_at_offset() instead.
+ * Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
  *
  * Returns: a newly allocated string containing the text after @offset bounded
  *   by the specified @boundary_type. Use g_free() to free the returned string.
@@ -497,8 +501,7 @@ atk_text_get_text_at_offset (AtkText          *text,
  *
  * Gets the specified text.
  *
- * Deprecated: This method is deprecated since ATK version
- * 2.9.3. Please use atk_text_get_string_at_offset() instead.
+ * Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
  *
  * Returns: a newly allocated string containing the text before @offset bounded
  *   by the specified @boundary_type. Use g_free() to free the returned string.
@@ -577,11 +580,12 @@ atk_text_get_text_before_offset (AtkText          *text,
  * 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
+ * Since: 2.10
  *
- * 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.
+ * Returns: (nullable): 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,
@@ -1066,10 +1070,8 @@ atk_text_get_range_extents (AtkText          *text,
 
   g_return_if_fail (ATK_IS_TEXT (text));
   g_return_if_fail (rect);
+  g_return_if_fail (start_offset >= 0 && start_offset < end_offset);
 
-  if (start_offset < 0 || start_offset >= end_offset)
-    return;
- 
   iface = ATK_TEXT_GET_IFACE (text);
 
   if (iface->get_range_extents)
@@ -1090,7 +1092,6 @@ atk_text_get_range_extents (AtkText          *text,
  *
  * Returns: (array zero-terminated=1): Array of AtkTextRange. The last
  *          element of the array returned by this function will be NULL.
- * Virtual: get_bounded_ranges
  **/
 AtkTextRange**
 atk_text_get_bounded_ranges (AtkText          *text,
@@ -1261,8 +1262,9 @@ atk_text_attribute_for_name (const gchar *name)
  *
  * Gets the value for the index of the #AtkTextAttribute
  *
- * Returns: a string containing the value; this string should not be freed;
- * NULL is returned if there are no values maintained for the attr value. 
+ * Returns: (nullable): a string containing the value; this string
+ * should not be freed; %NULL is returned if there are no values
+ * maintained for the attr value.
  **/
 const gchar*
 atk_text_attribute_get_value (AtkTextAttribute attr,