atspi-text

## atspi-text atspi-text |

## Synopsis

                        AtspiRange;
    #define             ATSPI_TYPE_RANGE
    AtspiRange *        atspi_range_copy                    (AtspiRange *src);
                        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

      GInterface
       +----AtspiText

## Known Implementations

AtspiText is implemented by AtspiAccessible.

## Description

## Details

### AtspiRange

    typedef struct {
      gint start_offset;
      gint end_offset;
    } AtspiRange;

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

`src` : |
Returns : |

### AtspiTextRange

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

### 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                 ();

Returns : |

### AtspiText

    typedef struct _AtspiText AtspiText;

### atspi_text_range_get_type ()

    GType               atspi_text_range_get_type           ();

Returns : |

### atspi_text_get_character_count ()

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

Get the character count of an AccessibleText object.

`obj` : | a pointer to the AtspiText object to query.
`error` : |
Returns : | a long integer 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);

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

`obj` : | a pointer to the AtspiText object to query.
`start_offset` : | a long indicating the start of the desired text range.
`end_offset` : | a long indicating the first character past the desired range.
`error` : |
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);

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

`obj` : | a pointer to the AtspiText object to query.
`error` : |
Returns : | a long integer 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);

Get the attributes applied to a range of text from an AtspiText object, and the bounds of the range. The text attributes correspond to CSS attributes where possible,

`obj` : | a pointer to the AtspiText object to query.
`offset` : | a long integer indicating the offset from which the attribute search is based.
`start_offset` : | a gint indicating the start of the desired text range. [out]
`end_offset` : | a gint indicating the first character past the desired range. [out]
`error` : |
Returns : | a GHashTable describing the attributes at the given character offset. [element-type gchar* gchar*][transfer full gchar* gchar*]

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

`obj` : | a pointer to the AtspiText object to query.
`offset` : | an integer indicating the offset from which the attribute search is based.
`include_defaults` : | a bool if False, 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 indicating the start of the desired text range. [out]
`end_offset` : | a gint indicating the first character past the desired range. [out]
`error` : |
Returns : | the AttributeSet defined at offset, optionally including the 'default' attributes. [element-type gchar* gchar*][transfer full gchar* gchar*]

### atspi_text_get_attribute_value ()

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

`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.
`error` : |
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);

Get the default attributes applied to an AtspiText object. The text attributes correspond to CSS attributes where possible, keys and values are delimited from one another via ":", and the delimiter between key/value pairs is ";". Thus "font-size:10;foreground-color:0,0,0" would be a valid return string. The combination of this attribute set and the attributes reported by atspi_text_getAttributes describes the entire set of text attributes over a range.

`obj` : | a pointer to the AtspiText object to query.
`error` : |
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 gchar* gchar*]

### atspi_text_set_caret_offset ()

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

Set the text caret position for an AtspiText object.

`obj` : | a pointer to the AtspiText object on which to operate.
`new_offset` : | the offset to which the text caret is to be moved.
`error` : |
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);

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

`obj` : | a pointer to the AtspiText object on which to operate.
`offset` : | an integer 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.
`error` : |
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);

Get 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 long integer 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.
`error` : |
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);

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

`obj` : | a pointer to the AtspiText object on which to operate.
`offset` : | an integer 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.
`error` : |
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);

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

`obj` : | a pointer to the AtspiText object on which to operate.
`offset` : | a long integer indicating the text offset where the desired character is located.
`error` : |
Returns : | an unsigned long integer which represents 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);

`obj` : | a pointer to the AtspiText object on which to operate.
`offset` : | an integer 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.
`error` : |
Returns : | A AtspiRect specifying the position and size of the character. Get the bounding box containing the glyph representing the character at a particular text offset.

### atspi_text_get_offset_at_point ()

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

Get 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.
`error` : |
Returns : | the offset (as an integer) 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);

`obj` : | a pointer to the AtspiText object on which to operate.
`start_offset` : | an integer indicating the offset of the first text character for whom boundary information is requested.
`end_offset` : | an integer 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.
`error` : |
Returns : | A AtspiRect giving the position and size of the specified range of text. Get the bounding box for text within a range in an AtspiText object.

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

Get 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.
`error` : |
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);

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

`obj` : | a pointer to the AtspiText object on which to operate.
`error` : |
Returns : | a long integer 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);

`obj` : |
`selection_num` : |
`error` : |
Returns : |

### atspi_text_add_selection ()

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

Select some text (add 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.
`error` : |
Returns : | TRUE if successful, FALSE otherwise.

### atspi_text_remove_selection ()

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

De-select a text selection.

`obj` : | a pointer to the AtspiText object on which to operate.
`selection_num` : | an integer indicating which (possibly of several) text selection to remove.
`error` : |
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);

Change 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 long int, the new starting offset for the selection.
`end_offset` : | a long int, the desired new offset of the first character after the selection.
`error` : |
Returns : | TRUE if successful, FALSE otherwise.