atspi-text: libatspi Reference Manual

atspi-text

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

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

Types and Values

struct	AtspiRange
#define	ATSPI_TYPE_RANGE
struct	AtspiTextRange
#define	ATSPI_TYPE_TEXT_RANGE
	AtspiText

Object Hierarchy

    GBoxed
    ├── AtspiRange
    ╰── 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.

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.

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.

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.

Types and Values

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.

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.

AtspiText

typedef struct _AtspiText AtspiText;