atspi-text

## atspi-text atspi-text — An interface implemented by objects which place textual information onscreen. |

## Synopsis

    struct              AtspiRange;
    #define             ATSPI_TYPE_RANGE
    AtspiRange *        atspi_range_copy                    (AtspiRange *src);
    struct              AtspiTextRange;
    #define             ATSPI_TYPE_TEXT_RANGE
    GType               atspi_text_get_type                 ();
                        AtspiText;
    GType               atspi_text_range_get_type           ();
    gint                atspi_text_get_character_count      (AtspiText *obj,
                                                             GError **error);
    gchar *             atspi_text_get_text                 (AtspiText *obj,
                                                             gint start_offset,
                                                             gint end_offset,
                                                             GError **error);
    gint                atspi_text_get_caret_offset         (AtspiText *obj,
                                                             GError **error);
    GHashTable *        atspi_text_get_attributes           (AtspiText *obj,
                                                             gint offset,
                                                             gint *start_offset,
                                                             gint *end_offset,
                                                             GError **error);
    GHashTable *        atspi_text_get_attribute_run        (AtspiText *obj,
                                                             gint offset,
                                                             gboolean include_defaults,
                                                             gint *start_offset,
                                                             gint *end_offset,
                                                             GError **error);
    gchar *             atspi_text_get_attribute_value      (AtspiText *obj,
                                                             gint offset,
                                                             gchar *attribute_name,
                                                             GError **error);
    GHashTable *        atspi_text_get_default_attributes   (AtspiText *obj,
                                                             GError **error);
    gboolean            atspi_text_set_caret_offset         (AtspiText *obj,
                                                             gint new_offset,
                                                             GError **error);
    AtspiTextRange *    atspi_text_get_text_before_offset   (AtspiText *obj,
                                                             gint offset,
                                                             AtspiTextBoundaryType type,
                                                             GError **error);
    AtspiTextRange *    atspi_text_get_text_at_offset       (AtspiText *obj,
                                                             gint offset,
                                                             AtspiTextBoundaryType type,
                                                             GError **error);
    AtspiTextRange *    atspi_text_get_text_after_offset    (AtspiText *obj,
                                                             gint offset,
                                                             AtspiTextBoundaryType type,
                                                             GError **error);
    guint               atspi_text_get_character_at_offset  (AtspiText *obj,
                                                             gint offset,
                                                             GError **error);
    AtspiRect *         atspi_text_get_character_extents    (AtspiText *obj,
                                                             gint offset,
                                                             AtspiCoordType type,
                                                             GError **error);
    gint                atspi_text_get_offset_at_point      (AtspiText *obj,
                                                             gint x,
                                                             gint y,
                                                             AtspiCoordType type,
                                                             GError **error);
    AtspiRect *         atspi_text_get_range_extents        (AtspiText *obj,
                                                             gint start_offset,
                                                             gint end_offset,
                                                             AtspiCoordType type,
                                                             GError **error);
    GArray *            atspi_text_get_bounded_ranges       (AtspiText *obj,
                                                             gint x,
                                                             gint y,
                                                             gint width,
                                                             gint height,
                                                             AtspiCoordType type,
                                                             AtspiTextClipType clipTypeX,
                                                             AtspiTextClipType clipTypeY,
                                                             GError **error);
    gint                atspi_text_get_n_selections         (AtspiText *obj,
                                                             GError **error);
    AtspiRange *        atspi_text_get_selection            (AtspiText *obj,
                                                             gint selection_num,
                                                             GError **error);
    gboolean            atspi_text_add_selection            (AtspiText *obj,
                                                             gint start_offset,
                                                             gint end_offset,
                                                             GError **error);
    gboolean            atspi_text_remove_selection         (AtspiText *obj,
                                                             gint selection_num,
                                                             GError **error);
    gboolean            atspi_text_set_selection            (AtspiText *obj,
                                                             gint selection_num,
                                                             gint start_offset,
                                                             gint end_offset,
                                                             GError **error);

## Object Hierarchy

      GBoxed
       +----AtspiRange

      GBoxed
       +----AtspiTextRange

      GInterface
       +----AtspiText

## Known Implementations

AtspiText is implemented by AtspiAccessible.

## Description

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 boc information for glyphs and substrings. It also alows portions of text to be selected, if the objects StateSet includes STATE_SELECTABLE_TEXT.

## Details

### struct AtspiRange

    struct AtspiRange {
      gint start_offset;
      gint end_offset;
    };

### ATSPI_TYPE_RANGE

    #define ATSPI_TYPE_RANGE atspi_range_get_type ()

The GType for a boxed type holding a range within a text bock.

### atspi_range_copy ()

    AtspiRange *        atspi_range_copy                    (AtspiRange *src);

Gets a copy of an AtspiRange object.

`src` : | a pointer to the source AtspiRange object that will be copied.
Returns : | the AtspiRange copy of an AtspiRange object.

### struct AtspiTextRange

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

### ATSPI_TYPE_TEXT_RANGE

    #define ATSPI_TYPE_TEXT_RANGE atspi_text_range_get_type ()

The GType for a boxed type holding a range within a text bock.

### atspi_text_get_type ()

    GType               atspi_text_get_type                 ();

### AtspiText

    typedef struct _AtspiText AtspiText;

### 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.

`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.

`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.

`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);

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>

`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.

`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);

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

`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.

### 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.

`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.

`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.

`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);

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

`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.

`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.

`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.

`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.

`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.

`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`).

`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.

`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.

`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.

`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.

`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.

`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.