Atspi.Text

g Atspi.Text Atspi.Text GObject.GInterface GObject.GInterface GObject.GInterface->Atspi.Text

Implementations:

Atspi.Accessible

Methods

add_selection (start_offset, end_offset)

get_attribute_run (offset, include_defaults)

get_bounded_ranges (x, y, width, height, type, clipTypeX, clipTypeY)

get_caret_offset ()

get_character_at_offset (offset)

get_character_count ()

get_character_extents (offset, type)

get_default_attributes ()

get_n_selections ()

get_offset_at_point (x, y, type)

get_range_extents (start_offset, end_offset, type)

get_selection (selection_num)

get_string_at_offset (offset, granularity)

get_text (start_offset, end_offset)

get_text_after_offset (offset, type)

get_text_at_offset (offset, type)

get_text_attribute_value (offset, attribute_name)

get_text_attributes (offset)

get_text_before_offset (offset, type)

remove_selection (selection_num)

scroll_substring_to (start_offset, end_offset, type)

scroll_substring_to_point (start_offset, end_offset, coords, x, y)

set_caret_offset (new_offset)

set_selection (selection_num, start_offset, end_offset)

Virtual Methods

None

Properties

None

Signals

None

Fields

None

Class Details

class Atspi.Text
Bases:

GObject.GInterface

An interface implemented by objects which place textual information onscreen.

The text interface should be implemented by objects which place textual information onscreen as character strings or glyphs. The text interface allows access to textual content including display attributes and semantic hints associated with runs of text, and to bounding information for glyphs and substrings. It also allows portions of text to be selected, if the objects StateSet includes STATE_SELECTABLE_TEXT.

add_selection(start_offset, end_offset)
Parameters:
  • start_offset (int) – the starting offset of the desired new selection.

  • end_offset (int) – the offset of the first character after the new selection.

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

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

get_attribute_run(offset, include_defaults)
Parameters:
  • offset (int) – a int indicating the offset from which the attribute search is based.

  • include_defaults (bool) – 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.

Raises:

GLib.Error

Returns:

a GLib.HashTable with attributes defined at the indicated offset, optionally including the ‘default’ ones.

start_offset:

a int pointer indicating the start of the desired text range.

end_offset:

a int pointer indicating the first character past the desired range.

Return type:

({str: str}, start_offset: int, end_offset: int)

Gets a set of attributes applied to a range of text from an Atspi.Text object, optionally including its ‘default’ attributes.

get_bounded_ranges(x, y, width, height, type, clipTypeX, clipTypeY)
Parameters:
  • x (int) – the ‘starting’ x coordinate of the bounding box.

  • y (int) – the ‘starting’ y coordinate of the bounding box.

  • width (int) – the x extent of the bounding box.

  • height (int) – the y extent of the bounding box.

  • type (Atspi.CoordType) – an #AccessibleCoordType indicating the coordinate system to use for the returned values.

  • clipTypeX (Atspi.TextClipType) – an Atspi.TextClipType indicating how to treat characters that intersect the bounding box’s x extents.

  • clipTypeY (Atspi.TextClipType) – an Atspi.TextClipType indicating how to treat characters that intersect the bounding box’s y extents.

Raises:

GLib.Error

Returns:

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

Return type:

[Atspi.TextRange]

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

get_caret_offset()
Raises:

GLib.Error

Returns:

a int indicating the current position of the text caret.

Return type:

int

Gets the current offset of the text caret in an Atspi.Text object.

get_character_at_offset(offset)
Parameters:

offset (int) – a int indicating the text offset where the desired character is located.

Raises:

GLib.Error

Returns:

a int 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.

Return type:

int

Gets the character at a given offset for an Atspi.Text object.

get_character_count()
Raises:

GLib.Error

Returns:

a int indicating the total number of characters in the #AccessibleText object.

Return type:

int

Gets the character count of an #AccessibleText object.

get_character_extents(offset, type)
Parameters:
  • offset (int) – a int indicating the offset of the text character for whom boundary information is requested.

  • type (Atspi.CoordType) – an #AccessibleCoordType indicating the coordinate system to use for the returned values.

Raises:

GLib.Error

Returns:

An Atspi.Rect specifying the position and size of the character.

Return type:

Atspi.Rect

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.

get_default_attributes()
Raises:

GLib.Error

Returns:

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

Return type:

{str: str}

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

get_n_selections()
Raises:

GLib.Error

Returns:

a int indicating the current number of non-contiguous text selections active within an Atspi.Text object.

Return type:

int

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

get_offset_at_point(x, y, type)
Parameters:
  • x (int) – the x coordinate of the point to be queried.

  • y (int) – the y coordinate of the point to be queried.

  • type (Atspi.CoordType) – an Atspi.CoordType indicating the coordinate system in which the values should be returned.

Raises:

GLib.Error

Returns:

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

Return type:

int

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

get_range_extents(start_offset, end_offset, type)
Parameters:
  • start_offset (int) – a int indicating the offset of the first text character for whom boundary information is requested.

  • end_offset (int) – a int indicating the offset of the text character after the last character for whom boundary information is requested.

  • type (Atspi.CoordType) – an Atspi.CoordType indicating the coordinate system to use for the returned values.

Raises:

GLib.Error

Returns:

An Atspi.Rect giving the position and size of the specified range of text.

Return type:

Atspi.Rect

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

get_selection(selection_num)
Parameters:

selection_num (int) – a int indicating which selection to query.

Raises:

GLib.Error

Return type:

Atspi.Range

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

get_string_at_offset(offset, granularity)
Parameters:
Raises:

GLib.Error

Returns:

a newly allocated string containing the text at the offset bounded by the specified granularity. Use GLib.free() to free the returned string. Returns None if the offset is invalid or no implementation is available.

Return type:

Atspi.TextRange

Gets a portion of the text exposed through an Atspi.Text 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.TextGranularity.CHAR the character at the offset is returned.

If granularity is Atspi.TextGranularity.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.TextGranularity.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.TextGranularity.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.TextGranularity.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.

New in version 2.9.90.

get_text(start_offset, end_offset)
Parameters:
  • start_offset (int) – a int indicating the start of the desired text range.

  • end_offset (int) – a int indicating the first character past the desired range.

Raises:

GLib.Error

Returns:

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

Return type:

str

Gets a range of text from an Atspi.Text 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.

get_text_after_offset(offset, type)
Parameters:
Raises:

GLib.Error

Returns:

an Atspi.TextRange 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.

Return type:

Atspi.TextRange

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

get_text_at_offset(offset, type)
Parameters:
Raises:

GLib.Error

Returns:

an Atspi.TextRange 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.

Return type:

Atspi.TextRange

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

Deprecated since version 2.10: Use Atspi.Text.get_string_at_offset.

get_text_attribute_value(offset, attribute_name)
Parameters:
  • offset (int) – The character offset at which to query the attribute.

  • attribute_name (str) – The attribute to query.

Raises:

GLib.Error

Returns:

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

Return type:

str or None

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

Deprecated since version 2.10: Use Atspi.Text.get_text_attribute_value instead.

get_text_attributes(offset)
Parameters:

offset (int) – a int indicating the offset from which the attribute search is based.

Raises:

GLib.Error

Returns:

a GLib.HashTable describing the attributes at the given character offset.

start_offset:

a int pointer indicating the start of the desired text range.

end_offset:

a int pointer indicating the first character past the desired range.

Return type:

({str: str}, start_offset: int, end_offset: int)

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

Deprecated since version 2.10: Use Atspi.Text.get_text_attributes instead.

get_text_before_offset(offset, type)
Parameters:
Raises:

GLib.Error

Returns:

an Atspi.TextRange 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.

Return type:

Atspi.TextRange

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

remove_selection(selection_num)
Parameters:

selection_num (int) – a int indicating which text selection to remove.

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

De-selects a text selection.

scroll_substring_to(start_offset, end_offset, type)
Parameters:
  • start_offset (int) – a int indicating the start of the desired text range.

  • end_offset (int) – a int indicating the first character past the desired range.

  • type (Atspi.ScrollType) – a Atspi.ScrollType indicating where the object should be placed on the screen.

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

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

scroll_substring_to_point(start_offset, end_offset, coords, x, y)
Parameters:
  • start_offset (int) – a int indicating the start of the desired text range.

  • end_offset (int) – a int indicating the first character past the desired range.

  • coords (Atspi.CoordType) – a Atspi.CoordType indicating whether the coordinates are relative to the screen, to the window, or to the parent object.

  • x (int) – the x coordinate of the point to reach

  • y (int) – the y coordinate of the point to reach

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

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

set_caret_offset(new_offset)
Parameters:

new_offset (int) – the offset to which the text caret is to be moved.

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Moves the text caret to a given position.

set_selection(selection_num, start_offset, end_offset)
Parameters:
  • selection_num (int) – a zero-offset index indicating which text selection to modify.

  • start_offset (int) – a int indicating the new starting offset for the selection.

  • end_offset (int) – a int indicating the desired new offset of the first character after the selection.

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Changes the bounds of an existing Atspi.Text text selection.