## atspi-text 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;