Functions
atk_text_get_text ()
gchar *
atk_text_get_text (AtkText *text,
gint start_offset,
gint end_offset);
Gets the specified text.
Returns
a newly allocated string containing the text from start_offset
up
to, but not including end_offset
. Use g_free() to free the returned
string.
atk_text_get_character_at_offset ()
gunichar
atk_text_get_character_at_offset (AtkText *text,
gint offset);
Gets the specified text.
Returns
the character at offset
or 0 in the case of failure.
atk_text_get_text_after_offset ()
gchar *
atk_text_get_text_after_offset (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
atk_text_get_text_after_offset has been deprecated since version 2.9.3 and should not be used in newly-written code.
Please use atk_text_get_string_at_offset() instead.
Gets the specified text.
Returns
a newly allocated string containing the text after offset
bounded
by the specified boundary_type
. Use g_free() to free the returned
string.
atk_text_get_text_at_offset ()
gchar *
atk_text_get_text_at_offset (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
atk_text_get_text_at_offset is deprecated and should not be used in newly-written code.
This method is deprecated since ATK version
2.9.4. Please use atk_text_get_string_at_offset() instead.
Gets the specified text.
If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the
offset is returned.
If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START 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 the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START 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 the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
string is from the line start at or before the offset to the line
start after the offset.
Returns
a newly allocated string containing the text at offset
bounded
by the specified boundary_type
. Use g_free() to free the returned
string.
atk_text_get_text_before_offset ()
gchar *
atk_text_get_text_before_offset (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
atk_text_get_text_before_offset has been deprecated since version 2.9.3 and should not be used in newly-written code.
Please use atk_text_get_string_at_offset() instead.
Gets the specified text.
Returns
a newly allocated string containing the text before offset
bounded
by the specified boundary_type
. Use g_free() to free the returned
string.
atk_text_get_string_at_offset ()
gchar *
atk_text_get_string_at_offset (AtkText *text,
gint offset,
AtkTextGranularity granularity,
gint *start_offset,
gint *end_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.
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.
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.
[nullable]
Since: 2.10
atk_text_get_caret_offset ()
gint
atk_text_get_caret_offset (AtkText *text);
Gets the offset of the position of the caret (cursor).
Returns
the character offset of the position of the caret or -1 if
the caret is not located inside the element or in the case of
any other failure.
atk_text_get_character_extents ()
void
atk_text_get_character_extents (AtkText *text,
gint offset,
gint *x,
gint *y,
gint *width,
gint *height,
AtkCoordType coords);
If the extent can not be obtained (e.g. missing support), all of x, y, width,
height are set to -1.
Get the bounding box containing the glyph representing the character at
a particular text offset.
atk_text_get_run_attributes ()
AtkAttributeSet *
atk_text_get_run_attributes (AtkText *text,
gint offset,
gint *start_offset,
gint *end_offset);
Creates an AtkAttributeSet which consists of the attributes explicitly
set at the position offset
in the text. start_offset
and end_offset
are
set to the start and end of the range around offset
where the attributes are
invariant. Note that end_offset
is the offset of the first character
after the range. See the enum AtkTextAttribute for types of text
attributes that can be returned. Note that other attributes may also be
returned.
atk_text_get_default_attributes ()
AtkAttributeSet *
atk_text_get_default_attributes (AtkText *text);
Creates an AtkAttributeSet which consists of the default values of
attributes for the text. See the enum AtkTextAttribute for types of text
attributes that can be returned. Note that other attributes may also be
returned.
atk_text_get_character_count ()
gint
atk_text_get_character_count (AtkText *text);
Gets the character count.
Returns
the number of characters or -1 in case of failure.
atk_text_get_offset_at_point ()
gint
atk_text_get_offset_at_point (AtkText *text,
gint x,
gint y,
AtkCoordType coords);
Gets the offset of the character located at coordinates x
and y
. x
and y
are interpreted as being relative to the screen or this widget's window
depending on coords
.
Returns
the offset to the character which is located at the specified
x
and y
coordinates of -1 in case of failure.
atk_text_get_bounded_ranges ()
AtkTextRange **
atk_text_get_bounded_ranges (AtkText *text,
AtkTextRectangle *rect,
AtkCoordType coord_type,
AtkTextClipType x_clip_type,
AtkTextClipType y_clip_type);
Get the ranges of text in the specified bounding box.
[virtual get_bounded_ranges]
Returns
Array of AtkTextRange. The last
element of the array returned by this function will be NULL.
[array zero-terminated=1]
Since: 1.3
atk_text_get_range_extents ()
void
atk_text_get_range_extents (AtkText *text,
gint start_offset,
gint end_offset,
AtkCoordType coord_type,
AtkTextRectangle *rect);
Get the bounding box for text within the specified range.
If the extents can not be obtained (e.g. or missing support), the rectangle
fields are set to -1.
Since: 1.3
atk_text_free_ranges ()
void
atk_text_free_ranges (AtkTextRange **ranges);
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.
Since: 1.3
atk_text_get_n_selections ()
gint
atk_text_get_n_selections (AtkText *text);
Gets the number of selected regions.
Returns
The number of selected regions, or -1 in the case of failure.
atk_text_get_selection ()
gchar *
atk_text_get_selection (AtkText *text,
gint selection_num,
gint *start_offset,
gint *end_offset);
Gets the text from the specified selection.
Returns
a newly allocated string containing the selected text. Use g_free()
to free the returned string.
atk_text_add_selection ()
gboolean
atk_text_add_selection (AtkText *text,
gint start_offset,
gint end_offset);
Adds a selection bounded by the specified offsets.
atk_text_remove_selection ()
gboolean
atk_text_remove_selection (AtkText *text,
gint selection_num);
Removes the specified selection.
atk_text_set_selection ()
gboolean
atk_text_set_selection (AtkText *text,
gint selection_num,
gint start_offset,
gint end_offset);
Changes the start and end offset of the specified selection.
atk_text_set_caret_offset ()
gboolean
atk_text_set_caret_offset (AtkText *text,
gint offset);
Sets the caret (cursor) position to the specified offset
.
atk_attribute_set_free ()
void
atk_attribute_set_free (AtkAttributeSet *attrib_set);
Frees the memory used by an AtkAttributeSet, including all its
AtkAttributes.
atk_text_attribute_get_name ()
const gchar *
atk_text_attribute_get_name (AtkTextAttribute attr);
Gets the name corresponding to the AtkTextAttribute
Returns
a string containing the name; this string should not be freed
atk_text_attribute_for_name ()
AtkTextAttribute
atk_text_attribute_for_name (const gchar *name);
Get the AtkTextAttribute type corresponding to a text attribute name.
Returns
the AtkTextAttribute enumerated type corresponding to the specified
name, or ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute
is found.
atk_text_attribute_get_value ()
const gchar *
atk_text_attribute_get_value (AtkTextAttribute attr,
gint index_);
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.
[nullable]
atk_text_scroll_substring_to ()
gboolean
atk_text_scroll_substring_to (AtkText *text,
gint start_offset,
gint end_offset,
AtkScrollType type);
Makes a substring of text
visible on the screen by scrolling all necessary parents.
Returns
whether scrolling was successful.
Since: 2.32
atk_text_scroll_substring_to_point ()
gboolean
atk_text_scroll_substring_to_point (AtkText *text,
gint start_offset,
gint end_offset,
AtkCoordType coords,
gint x,
gint y);
Move the top-left of a substring of text
to a given position of the screen
by scrolling all necessary parents.
Returns
whether scrolling was successful.
Since: 2.32
Types and Values
AtkText
typedef struct _AtkText AtkText;
struct AtkTextIface
struct AtkTextIface {
GTypeInterface parent;
gchar* (* get_text) (AtkText *text,
gint start_offset,
gint end_offset);
gchar* (* get_text_after_offset) (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
gchar* (* get_text_at_offset) (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
gunichar (* get_character_at_offset) (AtkText *text,
gint offset);
gchar* (* get_text_before_offset) (AtkText *text,
gint offset,
AtkTextBoundary boundary_type,
gint *start_offset,
gint *end_offset);
gint (* get_caret_offset) (AtkText *text);
AtkAttributeSet* (* get_run_attributes) (AtkText *text,
gint offset,
gint *start_offset,
gint *end_offset);
AtkAttributeSet* (* get_default_attributes) (AtkText *text);
void (* get_character_extents) (AtkText *text,
gint offset,
gint *x,
gint *y,
gint *width,
gint *height,
AtkCoordType coords);
gint (* get_character_count) (AtkText *text);
gint (* get_offset_at_point) (AtkText *text,
gint x,
gint y,
AtkCoordType coords);
gint (* get_n_selections) (AtkText *text);
gchar* (* get_selection) (AtkText *text,
gint selection_num,
gint *start_offset,
gint *end_offset);
gboolean (* add_selection) (AtkText *text,
gint start_offset,
gint end_offset);
gboolean (* remove_selection) (AtkText *text,
gint selection_num);
gboolean (* set_selection) (AtkText *text,
gint selection_num,
gint start_offset,
gint end_offset);
gboolean (* set_caret_offset) (AtkText *text,
gint offset);
/*
* signal handlers
*/
void (* text_changed) (AtkText *text,
gint position,
gint length);
void (* text_caret_moved) (AtkText *text,
gint location);
void (* text_selection_changed) (AtkText *text);
void (* text_attributes_changed) (AtkText *text);
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);
gchar* (* get_string_at_offset) (AtkText *text,
gint offset,
AtkTextGranularity granularity,
gint *start_offset,
gint *end_offset);
/*
* Scrolls this text range so it becomes visible on the screen.
*
* scroll_substring_to lets the implementation compute an appropriate target
* position on the screen, with type used as a positioning hint.
*
* scroll_substring_to_point lets the client specify a precise target position
* on the screen for the top-left of the substring.
*
* Since ATK 2.32
*/
gboolean (* scroll_substring_to) (AtkText *text,
gint start_offset,
gint end_offset,
AtkScrollType type);
gboolean (* scroll_substring_to_point) (AtkText *text,
gint start_offset,
gint end_offset,
AtkCoordType coords,
gint x,
gint y);
};
enum AtkTextBoundary
Text boundary types used for specifying boundaries for regions of text.
This enumeration is deprecated since 2.9.4 and should not be used. Use
AtkTextGranularity with atk_text_get_string_at_offset instead.
enum AtkTextGranularity
Text granularity types used for specifying the granularity of the region of
text we are interested in.
enum AtkTextClipType
Describes the type of clipping required.
struct AtkTextRange
struct AtkTextRange {
AtkTextRectangle bounds;
gint start_offset;
gint end_offset;
gchar* content;
};
A structure used to describe a text range.
struct AtkTextRectangle
struct AtkTextRectangle {
gint x;
gint y;
gint width;
gint height;
};
A structure used to store a rectangle used by AtkText.
enum AtkTextAttribute
Describes the text attributes supported
Signal Details
The “text-attributes-changed” signal
void
user_function (AtkText *atktext,
gpointer user_data)
The "text-attributes-changed" signal is emitted when the text
attributes of the text of an object which implements AtkText
changes.
Flags: Run Last
The “text-caret-moved” signal
void
user_function (AtkText *atktext,
gint arg1,
gpointer user_data)
The "text-caret-moved" signal is emitted when the caret
position of the text of an object which implements AtkText
changes.
Flags: Run Last
The “text-changed” signal
void
user_function (AtkText *atktext,
gint arg1,
gint arg2,
gpointer user_data)
The "text-changed" signal is emitted when the text of the
object which implements the AtkText interface changes, This
signal will have a detail which is either "insert" or
"delete" which identifies whether the text change was an
insertion or a deletion.
AtkText::text-changed has been deprecated since version 2.9.4 and should not be used in newly-written code.
Use “text-insert” or
“text-remove” instead.
Flags: Has Details
The “text-insert” signal
void
user_function (AtkText *atktext,
gint arg1,
gint arg2,
gchar *arg3,
gpointer user_data)
The "text-insert" signal is emitted when a new text is
inserted. If the signal was not triggered by the user
(e.g. typing or pasting text), the "system" detail should be
included.
Flags: Has Details
The “text-remove” signal
void
user_function (AtkText *atktext,
gint arg1,
gint arg2,
gchar *arg3,
gpointer user_data)
The "text-remove" signal is emitted when a new text is
removed. If the signal was not triggered by the user
(e.g. typing or pasting text), the "system" detail should be
included.
Flags: Has Details
The “text-selection-changed” signal
void
user_function (AtkText *atktext,
gpointer user_data)
The "text-selection-changed" signal is emitted when the
selected text of an object which implements AtkText changes.
Flags: Run Last