diff options
author | Mario Sanchez Prada <mario.prada@samsung.com> | 2013-08-09 18:11:53 +0100 |
---|---|---|
committer | Mario Sanchez Prada <mario.prada@samsung.com> | 2013-08-14 14:27:44 +0100 |
commit | 3261a8a792f6688b5575512b8828eea262164713 (patch) | |
tree | a27885f34d6cd530728412771bf996ebf8caf8d8 | |
parent | 794a9bf8ad9eb11fe8b120155665671854f05585 (diff) | |
download | atk-3261a8a792f6688b5575512b8828eea262164713.tar.gz |
Implement atk_text_get_string_at_offset() and deprecate old API
https://bugzilla.gnome.org/show_bug.cgi?id=705580
-rw-r--r-- | atk/atk.symbols | 2 | ||||
-rwxr-xr-x | atk/atktext.c | 86 | ||||
-rwxr-xr-x | atk/atktext.h | 63 | ||||
-rw-r--r-- | 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> |