atspi-text: libatspi Reference Manual

atspi-text

Functions

AtspiRange *	atspi_range_copy ()
GType	atspi_text_get_type ()
GType	atspi_text_range_get_type ()
gint	atspi_text_get_character_count ()
gchar *	atspi_text_get_text ()
gint	atspi_text_get_caret_offset ()
GHashTable *	atspi_text_get_attributes ()
GHashTable *	atspi_text_get_attribute_run ()
gchar *	atspi_text_get_attribute_value ()
GHashTable *	atspi_text_get_default_attributes ()
gboolean	atspi_text_set_caret_offset ()
AtspiTextRange *	atspi_text_get_text_before_offset ()
AtspiTextRange *	atspi_text_get_text_at_offset ()
AtspiTextRange *	atspi_text_get_text_after_offset ()
guint	atspi_text_get_character_at_offset ()
AtspiRect *	atspi_text_get_character_extents ()
gint	atspi_text_get_offset_at_point ()
AtspiRect *	atspi_text_get_range_extents ()
GArray *	atspi_text_get_bounded_ranges ()
gint	atspi_text_get_n_selections ()
AtspiRange *	atspi_text_get_selection ()
gboolean	atspi_text_add_selection ()
gboolean	atspi_text_remove_selection ()
gboolean	atspi_text_set_selection ()
AtspiTextRange *	atspi_text_get_string_at_offset ()
gchar *	atspi_text_get_text_attribute_value ()
GHashTable *	atspi_text_get_text_attributes ()
gboolean	atspi_text_scroll_substring_to ()
gboolean	atspi_text_scroll_substring_to_point ()

Types and Values

struct	AtspiRange
struct	AtspiTextRange
	AtspiText

Object Hierarchy

    GBoxed
    ├── AtspiRange
    ╰── AtspiTextRange
    GInterface
    ╰── AtspiText

Known Implementations

AtspiText is implemented by AtspiAccessible.

Description

Functions

atspi_range_copy ()

AtspiRange *
atspi_range_copy (AtspiRange *src);

Gets a copy of an AtspiRange object.

Parameters

src

a pointer to the source AtspiRange object that will be copied.

Returns

the AtspiRange copy of an AtspiRange object.

atspi_text_get_type ()

GType
atspi_text_get_type ();

atspi_text_range_get_type ()

GType
atspi_text_range_get_type ();

atspi_text_get_character_count ()

gint
atspi_text_get_character_count (AtspiText *obj,
                                GError **error);

Gets the character count of an AccessibleText object.

Parameters

obj

a pointer to the AtspiText object to query.

Returns

a gint indicating the total number of characters in the AccessibleText object.

atspi_text_get_text ()

gchar *
atspi_text_get_text (AtspiText *obj,
                     gint start_offset,
                     gint end_offset,
                     GError **error);

Gets a range of text from an AtspiText object. The number of bytes in the returned string may exceed either end_offset or start_offset, since UTF-8 is a variable-width encoding.

Parameters

obj	a pointer to the AtspiText object to query.
start_offset	a gint indicating the start of the desired text range.
end_offset	a gint indicating the first character past the desired range.

Returns

a text string containing characters from start_offset to end_offset -1, inclusive, encoded as UTF-8.

atspi_text_get_caret_offset ()

gint
atspi_text_get_caret_offset (AtspiText *obj,
                             GError **error);

Gets the current offset of the text caret in an AtspiText object.

Parameters

obj

a pointer to the AtspiText object to query.

Returns

a gint indicating the current position of the text caret.

atspi_text_get_attributes ()

GHashTable *
atspi_text_get_attributes (AtspiText *obj,
                           gint offset,
                           gint *start_offset,
                           gint *end_offset,
                           GError **error);

atspi_text_get_attributes has been deprecated since version 2.10 and should not be used in newly-written code.

Use atspi_text_get_text_attributes instead.

Gets the attributes applied to a range of text from an AtspiText object. The text attributes correspond to CSS attributes where possible.

<em>DEPRECATED</em>

[rename-to atspi_text_get_text_attributes]

Parameters

obj	a pointer to the AtspiText object to query.
offset	a gint indicating the offset from which the attribute search is based.
start_offset	a gint pointer indicating the start of the desired text range.	[out]
end_offset	a gint pointer indicating the first character past the desired range.	[out]

Returns

a GHashTable describing the attributes at the given character offset.

[element-type gchar* gchar*][transfer full]

atspi_text_get_attribute_run ()

GHashTable *
atspi_text_get_attribute_run (AtspiText *obj,
                              gint offset,
                              gboolean include_defaults,
                              gint *start_offset,
                              gint *end_offset,
                              GError **error);

Gets a set of attributes applied to a range of text from an AtspiText object, optionally including its 'default' attributes.

Parameters

obj	a pointer to the AtspiText object to query.
offset	a gint indicating the offset from which the attribute search is based.
include_defaults	a bool that, when set as FALSE, indicates the call should only return those attributes which are explicitly set on the current attribute run, omitting any attributes which are inherited from the default values.
start_offset	a gint pointer indicating the start of the desired text range.	[out]
end_offset	a gint pointer indicating the first character past the desired range.	[out]

Returns

a GHashTable with attributes defined at the indicated offset, optionally including the 'default' ones.

[element-type gchar* gchar*][transfer full]

atspi_text_get_attribute_value ()

gchar *
atspi_text_get_attribute_value (AtspiText *obj,
                                gint offset,
                                gchar *attribute_name,
                                GError **error);

atspi_text_get_attribute_value has been deprecated since version 2.10 and should not be used in newly-written code.

Use atspi_text_get_text_attribute_value instead.

Gets the value of a named attribute at a given offset.

[rename-to atspi_text_get_text_attribute_value]

Parameters

obj	a pointer to the AtspiText object to query.
offset	The character offset at which to query the attribute.
attribute_name	The attribute to query.

Returns

the value of a given attribute at the given offset, or NULL if not present.

[nullable]

atspi_text_get_default_attributes ()

GHashTable *
atspi_text_get_default_attributes (AtspiText *obj,
                                   GError **error);

Gets the default attributes applied to an AtspiText object. The text attributes correspond to CSS attributes where possible. The combination of this attribute set and the attributes reported by atspi_text_get_attributes describes the entire set of text attributes over a range.

Parameters

obj

a pointer to the AtspiText object to query.

Returns

a GHashTable containing the default attributes applied to a text object, (exclusive of explicitly-set attributes), encoded as UTF-8.

[element-type gchar* gchar*][transfer full]

atspi_text_set_caret_offset ()

gboolean
atspi_text_set_caret_offset (AtspiText *obj,
                             gint new_offset,
                             GError **error);

Moves the text caret to a given position.

Parameters

obj	a pointer to the AtspiText object on which to operate.
new_offset	the offset to which the text caret is to be moved.

Returns

TRUE if successful, FALSE otherwise.

atspi_text_get_text_before_offset ()

AtspiTextRange *
atspi_text_get_text_before_offset (AtspiText *obj,
                                   gint offset,
                                   AtspiTextBoundaryType type,
                                   GError **error);

Gets delimited text from an AtspiText object which precedes a given text offset.

Parameters

obj	a pointer to the AtspiText object on which to operate.
offset	a gint indicating the offset from which the delimiter search is based.
type	an AtspiTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.

Returns

an AtspiTextRange containing a UTF-8 string representing the delimited text, both of whose delimiting boundaries are before the current offset, or an empty string if no such text exists.

atspi_text_get_text_at_offset ()

AtspiTextRange *
atspi_text_get_text_at_offset (AtspiText *obj,
                               gint offset,
                               AtspiTextBoundaryType type,
                               GError **error);

atspi_text_get_text_at_offset has been deprecated since version 2.10 and should not be used in newly-written code.

Use atspi_text_get_string_at_offset.

Gets delimited text from an AtspiText object which includes a given text offset.

Parameters

obj	a pointer to the AtspiText object on which to operate.
offset	a gint indicating the offset from which the delimiter search is based.
type	an AtspiTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.

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.

atspi_text_get_text_after_offset ()

AtspiTextRange *
atspi_text_get_text_after_offset (AtspiText *obj,
                                  gint offset,
                                  AtspiTextBoundaryType type,
                                  GError **error);

Gets delimited text from an AtspiText object which follows a given text offset.

Parameters

obj	a pointer to the AtspiText object on which to operate.
offset	a gint indicating the offset from which the delimiter search is based.
type	an AtspiTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.

Returns

an AtspiTextRange containing a UTF-8 string representing the delimited text, both of whose delimiting boundaries are after or inclusive of the current offset, or an empty string if no such text exists.

atspi_text_get_character_at_offset ()

guint
atspi_text_get_character_at_offset (AtspiText *obj,
                                    gint offset,
                                    GError **error);

Gets the character at a given offset for an AtspiText object.

Parameters

obj	a pointer to the AtspiText object on which to operate.
offset	a gint indicating the text offset where the desired character is located.

Returns

a guint representing the UCS-4 unicode code point of the given character, or 0xFFFFFFFF if the character in question cannot be represented in the UCS-4 encoding.

atspi_text_get_character_extents ()

AtspiRect *
atspi_text_get_character_extents (AtspiText *obj,
                                  gint offset,
                                  AtspiCoordType type,
                                  GError **error);

Gets a bounding box containing the glyph representing the character at a particular text offset. The returned values are meaningful only if the Text has both STATE_VISIBLE and STATE_SHOWING.

Parameters

obj	a pointer to the AtspiText object on which to operate.
offset	a gint indicating the offset of the text character for whom boundary information is requested.
type	an AccessibleCoordType indicating the coordinate system to use for the returned values.

Returns

An AtspiRect specifying the position and size of the character.

atspi_text_get_offset_at_point ()

gint
atspi_text_get_offset_at_point (AtspiText *obj,
                                gint x,
                                gint y,
                                AtspiCoordType type,
                                GError **error);

Gets the character offset into the text at a given point.

Parameters

obj	a pointer to the AtspiText object on which to operate.
x	the x coordinate of the point to be queried.
y	the y coordinate of the point to be queried.
type	an AtspiCoordType indicating the coordinate system in which the values should be returned.

Returns

the offset (as a gint) at the point (x , y ) in the specified coordinate system.

atspi_text_get_range_extents ()

AtspiRect *
atspi_text_get_range_extents (AtspiText *obj,
                              gint start_offset,
                              gint end_offset,
                              AtspiCoordType type,
                              GError **error);

Gets the bounding box for text within a range in an AtspiText object. The returned values are meaningful only if the Text has both STATE_VISIBLE and STATE_SHOWING.

Parameters

obj	a pointer to the AtspiText object on which to operate.
start_offset	a gint indicating the offset of the first text character for whom boundary information is requested.
end_offset	a gint indicating the offset of the text character after the last character for whom boundary information is requested.
type	an AtspiCoordType indicating the coordinate system to use for the returned values.

Returns

An AtspiRect giving the position and size of the specified range of text.

atspi_text_get_bounded_ranges ()

GArray *
atspi_text_get_bounded_ranges (AtspiText *obj,
                               gint x,
                               gint y,
                               gint width,
                               gint height,
                               AtspiCoordType type,
                               AtspiTextClipType clipTypeX,
                               AtspiTextClipType clipTypeY,
                               GError **error);

Gets the ranges of text from an AtspiText object which lie within the bounds defined by (x , y ) and (x +width , y +height ).

Parameters

obj	a pointer to the AtspiText object on which to operate.
x	the 'starting' x coordinate of the bounding box.
y	the 'starting' y coordinate of the bounding box.
width	the x extent of the bounding box.
height	the y extent of the bounding box.
type	an AccessibleCoordType indicating the coordinate system to use for the returned values.
clipTypeX	an AtspiTextClipType indicating how to treat characters that intersect the bounding box's x extents.
clipTypeY	an AtspiTextClipType indicating how to treat characters that intersect the bounding box's y extents.

Returns

a null-terminated list of pointers to AtspiTextRange structs detailing the bounded text.

[transfer full][element-type AtspiTextRange*]

atspi_text_get_n_selections ()

gint
atspi_text_get_n_selections (AtspiText *obj,
                             GError **error);

Gets the number of active non-contiguous selections for an AtspiText object.

Parameters

obj

a pointer to the AtspiText object on which to operate.

Returns

a gint indicating the current number of non-contiguous text selections active within an AtspiText object.

atspi_text_get_selection ()

AtspiRange *
atspi_text_get_selection (AtspiText *obj,
                          gint selection_num,
                          GError **error);

Gets the bounds of the selection_num -th active text selection for an AtspiText object.

Parameters

obj	a pointer to the AtspiText object on which to operate.
selection_num	a gint indicating which selection to query.

atspi_text_add_selection ()

gboolean
atspi_text_add_selection (AtspiText *obj,
                          gint start_offset,
                          gint end_offset,
                          GError **error);

Selects some text (adds a text selection) in an AtspiText object.

Parameters

obj	a pointer to the AtspiText object on which to operate.
start_offset	the starting offset of the desired new selection.
end_offset	the offset of the first character after the new selection.

Returns

TRUE if successful, FALSE otherwise.

atspi_text_remove_selection ()

gboolean
atspi_text_remove_selection (AtspiText *obj,
                             gint selection_num,
                             GError **error);

De-selects a text selection.

Parameters

obj	a pointer to the AtspiText object on which to operate.
selection_num	a gint indicating which text selection to remove.

Returns

TRUE if successful, FALSE otherwise.

atspi_text_set_selection ()

gboolean
atspi_text_set_selection (AtspiText *obj,
                          gint selection_num,
                          gint start_offset,
                          gint end_offset,
                          GError **error);

Changes the bounds of an existing AtspiText text selection.

Parameters

obj	a pointer to the AtspiText object on which to operate.
selection_num	a zero-offset index indicating which text selection to modify.
start_offset	a gint indicating the new starting offset for the selection.
end_offset	a gint indicating the desired new offset of the first character after the selection.

Returns

TRUE if successful, FALSE otherwise.

atspi_text_get_string_at_offset ()

AtspiTextRange *
atspi_text_get_string_at_offset (AtspiText *obj,
                                 gint offset,
                                 AtspiTextGranularity granularity,
                                 GError **error);

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.

Parameters

obj	an AtspiText
offset	position
granularity	An AtspiTextGranularity

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.

Since: 2.9.90

atspi_text_get_text_attribute_value ()

gchar *
atspi_text_get_text_attribute_value (AtspiText *obj,
                                     gint offset,
                                     gchar *attribute_name,
                                     GError **error);

Gets the value of a named attribute at a given offset.

Parameters

obj	a pointer to the AtspiText object to query.
offset	The character offset at which to query the attribute.
attribute_name	The attribute to query.

Returns

the value of a given attribute at the given offset, or NULL if not present.

[nullable]

atspi_text_get_text_attributes ()

GHashTable *
atspi_text_get_text_attributes (AtspiText *obj,
                                gint offset,
                                gint *start_offset,
                                gint *end_offset,
                                GError **error);

Gets the attributes applied to a range of text from an AtspiText object. The text attributes correspond to CSS attributes where possible.

<em>DEPRECATED</em>

Parameters

obj	a pointer to the AtspiText object to query.
offset	a gint indicating the offset from which the attribute search is based.
start_offset	a gint pointer indicating the start of the desired text range.	[out]
end_offset	a gint pointer indicating the first character past the desired range.	[out]

Returns

a GHashTable describing the attributes at the given character offset.

[element-type gchar* gchar*][transfer full]

atspi_text_scroll_substring_to ()

gboolean
atspi_text_scroll_substring_to (AtspiText *obj,
                                gint start_offset,
                                gint end_offset,
                                AtspiScrollType type,
                                GError **error);

Scrolls whatever container of the AtspiText text range so it becomes visible on the screen.

Parameters

obj	a pointer to the AtspiText object on which to operate.
start_offset	a gint indicating the start of the desired text range.
end_offset	a gint indicating the first character past the desired range.
type	a AtspiScrollType indicating where the object should be placed on the screen.

Returns

TRUE if successful, FALSE otherwise.

atspi_text_scroll_substring_to_point ()

gboolean
atspi_text_scroll_substring_to_point (AtspiText *obj,
                                      gint start_offset,
                                      gint end_offset,
                                      AtspiCoordType coords,
                                      gint x,
                                      gint y,
                                      GError **error);

Scrolls whatever container of the AtspiText text range so it becomes visible on the screen at a given position.

Parameters

obj	a pointer to the AtspiText object on which to operate.
start_offset	a gint indicating the start of the desired text range.
end_offset	a gint indicating the first character past the desired range.
coords	a AtspiCoordType indicating whether the coordinates are relative to the screen, to the window, or to the parent object.
x	the x coordinate of the point to reach
y	the y coordinate of the point to reach

Returns

TRUE if successful, FALSE otherwise.

Types and Values

struct AtspiRange

struct AtspiRange {
  gint start_offset;
  gint end_offset;
};

struct AtspiTextRange

struct AtspiTextRange {
  gint start_offset;
  gint end_offset;
  gchar *content;
};

AtspiText

typedef struct _AtspiText AtspiText;