AtkText

ATK Library Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Details

struct AtkText

struct AtkText;

struct AtkTextIface

struct AtkTextIface
{
  GTypeInterface parent;

  gchar*         (* get_text)                     (AtkText          *text,
                                                   gint             start_offset,
                                                   gint             end_offset);
  gchar*         (* get_text_after_offset)        (AtkText          *text,
                                                   gint             offset,
                                                   AtkTextBoundary  boundary_type,
						   gint             *start_offset,
						   gint             *end_offset);
  gchar*         (* get_text_at_offset)           (AtkText          *text,
                                                   gint             offset,
                                                   AtkTextBoundary  boundary_type,
						   gint             *start_offset,
						   gint             *end_offset);
  gunichar       (* get_character_at_offset)      (AtkText          *text,
                                                   gint             offset);
  gchar*         (* get_text_before_offset)       (AtkText          *text,
                                                   gint             offset,
                                                   AtkTextBoundary  boundary_type,
 						   gint             *start_offset,
						   gint             *end_offset);
  gint           (* get_caret_offset)             (AtkText          *text);
  AtkAttributeSet* (* get_run_attributes)         (AtkText	    *text,
						   gint	  	    offset,
						   gint             *start_offset,
						   gint	 	    *end_offset);
  AtkAttributeSet* (* get_default_attributes)     (AtkText	    *text);
  void           (* get_character_extents)        (AtkText          *text,
                                                   gint             offset,
                                                   gint             *x,
                                                   gint             *y,
                                                   gint             *width,
                                                   gint             *height,
                                                   AtkCoordType	    coords);
  gint           (* get_character_count)          (AtkText          *text);
  gint           (* get_offset_at_point)          (AtkText          *text,
                                                   gint             x,
                                                   gint             y,
                                                   AtkCoordType	    coords);
  gint		 (* get_n_selections)		  (AtkText          *text);
  gchar*         (* get_selection)	          (AtkText          *text,
						   gint		    selection_num,
						   gint		    *start_offset,
						   gint		    *end_offset);
  gboolean       (* add_selection)		  (AtkText          *text,
						   gint		    start_offset,
						   gint		    end_offset);
  gboolean       (* remove_selection)		  (AtkText          *text,
						   gint             selection_num);
  gboolean       (* set_selection)		  (AtkText          *text,
						   gint		    selection_num,
						   gint		    start_offset,
						   gint		    end_offset);
  gboolean       (* set_caret_offset)             (AtkText          *text,
                                                   gint             offset);

  /*
   * signal handlers
   */
  void		 (* text_changed)                 (AtkText          *text,
                                                   gint             position,
                                                   gint             length);
  void           (* text_caret_moved)             (AtkText          *text,
                                                   gint             location);
  void           (* text_selection_changed)       (AtkText          *text);

  AtkFunction    pad1;
  AtkFunction    pad2;
  AtkFunction    pad3;
  AtkFunction    pad4;
};

enum AtkTextBoundary

typedef enum {
  ATK_TEXT_BOUNDARY_CHAR,
  ATK_TEXT_BOUNDARY_WORD_START,
  ATK_TEXT_BOUNDARY_WORD_END,
  ATK_TEXT_BOUNDARY_SENTENCE_START,
  ATK_TEXT_BOUNDARY_SENTENCE_END,
  ATK_TEXT_BOUNDARY_LINE_START,
  ATK_TEXT_BOUNDARY_LINE_END
} AtkTextBoundary;

Text boundary types used for specifying boundaries for regions of text

struct AtkAttribute

struct AtkAttribute {
  gchar* name;
  gchar* value;
};

A string name/value pair representing a text attribute.

gchar *`name`	The attribute name. Call atk_text_attr_get_name()
gchar *`value`	the value of the attribute, represented as a string. Call atk_text_attr_get_value() for those which are strings. For values which are numbers, the string representation of the number is in value.

AtkAttributeSet

typedef GSList AtkAttributeSet;

This is a singly-linked list (a GSList) of AtkAttribute. It is used by atk_text_get_run_attributes(), atk_text_get_default_attributes() and atk_editable_text_set_run_attributes()

enum AtkTextAttribute

typedef enum
{
  ATK_TEXT_ATTR_INVALID = 0,
  ATK_TEXT_ATTR_LEFT_MARGIN,
  ATK_TEXT_ATTR_RIGHT_MARGIN,
  ATK_TEXT_ATTR_INDENT,
  ATK_TEXT_ATTR_INVISIBLE,
  ATK_TEXT_ATTR_EDITABLE,
  ATK_TEXT_ATTR_PIXELS_ABOVE_LINES,
  ATK_TEXT_ATTR_PIXELS_BELOW_LINES,
  ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP,
  ATK_TEXT_ATTR_BG_FULL_HEIGHT,
  ATK_TEXT_ATTR_RISE,
  ATK_TEXT_ATTR_UNDERLINE,
  ATK_TEXT_ATTR_STRIKETHROUGH,
  ATK_TEXT_ATTR_SIZE,
  ATK_TEXT_ATTR_SCALE,
  ATK_TEXT_ATTR_WEIGHT,
  ATK_TEXT_ATTR_LANGUAGE,
  ATK_TEXT_ATTR_FAMILY_NAME,
  ATK_TEXT_ATTR_BG_COLOR,
  ATK_TEXT_ATTR_FG_COLOR,
  ATK_TEXT_ATTR_BG_STIPPLE,
  ATK_TEXT_ATTR_FG_STIPPLE,
  ATK_TEXT_ATTR_WRAP_MODE,
  ATK_TEXT_ATTR_DIRECTION,
  ATK_TEXT_ATTR_JUSTIFICATION,
  ATK_TEXT_ATTR_STRETCH,
  ATK_TEXT_ATTR_VARIANT,
  ATK_TEXT_ATTR_STYLE,
  ATK_TEXT_ATTR_LAST_DEFINED
} AtkTextAttribute;

Describes the text attributes supported

`ATK_TEXT_ATTR_INVALID`	Invalid attribute
`ATK_TEXT_ATTR_LEFT_MARGIN`	The pixel width of the left margin
`ATK_TEXT_ATTR_RIGHT_MARGIN`	The pixel width of the right margin
`ATK_TEXT_ATTR_INDENT`	The number of pixels that the text is indented
`ATK_TEXT_ATTR_INVISIBLE`	Either "true" or "false" indicating whether text is visible or not
`ATK_TEXT_ATTR_EDITABLE`	Either "true" or "false" indicating whether text is editable or not
`ATK_TEXT_ATTR_PIXELS_ABOVE_LINES`	Pixels of blank space to leave above each newline-terminated line.
`ATK_TEXT_ATTR_PIXELS_BELOW_LINES`	Pixels of blank space to leave below each newline-terminated line.
`ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP`	Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph).
`ATK_TEXT_ATTR_BG_FULL_HEIGHT`	"true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character.
`ATK_TEXT_ATTR_RISE`	Number of pixels that the characters are risen above the baseline
`ATK_TEXT_ATTR_UNDERLINE`	"none", "single", "double" or "low"
`ATK_TEXT_ATTR_STRIKETHROUGH`	"true" or "false" whether the text is strikethrough
`ATK_TEXT_ATTR_SIZE`	The size of the characters.
`ATK_TEXT_ATTR_SCALE`	The scale of the characters. The value is a string representation of a double
`ATK_TEXT_ATTR_WEIGHT`	The weight of the characters.
`ATK_TEXT_ATTR_LANGUAGE`	The language used
`ATK_TEXT_ATTR_FAMILY_NAME`	The font family name
`ATK_TEXT_ATTR_BG_COLOR`	The background color. The value is an RGB value of the format "`u`,`u`,`u`"
`ATK_TEXT_ATTR_FG_COLOR`	The foreground color. The value is an RGB value of the format "`u`,`u`,`u`"
`ATK_TEXT_ATTR_BG_STIPPLE`	"true" if a GdkBitmap is set for stippling the background color.
`ATK_TEXT_ATTR_FG_STIPPLE`	"true" if a GdkBitmap is set for stippling the foreground color.
`ATK_TEXT_ATTR_WRAP_MODE`	The wrap mode of the text, if any. Values are "none", "char" or "word"
`ATK_TEXT_ATTR_DIRECTION`	The direction of the text, if set. Values are "none", "ltr" or "rtl"
`ATK_TEXT_ATTR_JUSTIFICATION`	The justification of the text, if set. Values are "left", "right", "center" or "fill"
`ATK_TEXT_ATTR_STRETCH`	The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded"
`ATK_TEXT_ATTR_VARIANT`	The capitalization variant of the text, if set. Values are "normal" or "small_caps"
`ATK_TEXT_ATTR_STYLE`	The slant style of the text, if set. Values are "normal", "oblique" or "italic"
`ATK_TEXT_ATTR_LAST_DEFINED`	not a valid text attribute, used for finding end of enumeration

atk_text_get_text ()

gchar*      atk_text_get_text               (AtkText *text,
                                             gint start_offset,
                                             gint end_offset);

Gets the specified text.

`text` :	an AtkText
`start_offset` :	start position
`end_offset` :	end position
Returns :	the text from `start_offset` up to, but not including `end_offset`.

atk_text_get_character_at_offset ()

gunichar    atk_text_get_character_at_offset
                                            (AtkText *text,
                                             gint offset);

Gets the specified text.

`text` :	an AtkText
`offset` :	position
Returns :	the character at `offset`.

atk_text_get_text_after_offset ()

gchar*      atk_text_get_text_after_offset  (AtkText *text,
                                             gint offset,
                                             AtkTextBoundary boundary_type,
                                             gint *start_offset,
                                             gint *end_offset);

Gets the specified text.

If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character after the offset is returned.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start after the offset to the next word start.

The returned string will contain the word after the offset if the offset is inside a word or if the offset is not inside a word.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string is from the word end at or after the offset to the next work end.

The returned string will contain the word after the offset if the offset is inside a word and will contain the word after the word after the offset if the offset is not inside a word.

If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start after the offset to the next sentence start.

The returned string will contain the sentence after the offset if the offset is inside a sentence or if the offset is not inside a sentence.

If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string is from the sentence end at or after the offset to the next sentence end.

The returned string will contain the sentence after the offset if the offset is inside a sentence and will contain the sentence after the sentence after the offset if the offset is not inside a sentence.

If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start after the offset to the next line start.

If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string is from the line end at or after the offset to the next line start.

`text` :	an AtkText
`offset` :	position
`boundary_type` :	An AtkTextBoundary
`start_offset` :	the start offset of the returned string.
`end_offset` :	the end offset of the returned string.
Returns :	the text after `offset` bounded by the specified `boundary_type`.

atk_text_get_text_at_offset ()

gchar*      atk_text_get_text_at_offset     (AtkText *text,
                                             gint offset,
                                             AtkTextBoundary boundary_type,
                                             gint *start_offset,
                                             gint *end_offset);

Gets the specified text.

If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START 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 the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string is from the word end before the offset to the word end at or 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 after to the offset if the offset is not inside a word.

If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START 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 the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string is from the sentence end before the offset to the sentence end at or 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 after the offset if the offset is not inside a sentence.

If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset.

If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string is from the line end before the offset to the line end at or after the offset.

`text` :	an AtkText
`offset` :	position
`boundary_type` :	An AtkTextBoundary
`start_offset` :	the start offset of the returned string.
`end_offset` :	the end offset of the returned string.
Returns :	the text at `offset` bounded by the specified `boundary_type`.

atk_text_get_text_before_offset ()

gchar*      atk_text_get_text_before_offset (AtkText *text,
                                             gint offset,
                                             AtkTextBoundary boundary_type,
                                             gint *start_offset,
                                             gint *end_offset);

Gets the specified text.

If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character before the offset is returned.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start before the word start before the offset to the word start before the offset.

The returned string will contain the word before the offset if the offset is inside a word and will contain the word before the word before the offset if the offset is not inside a word.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string is from the word end before the word end at or before the offset to the word end at or before the offset.

The returned string will contain the word before the offset if the offset is inside a word or if the offset is not inside a word.

If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start before the sentence start before the offset to the sentence start before the offset.

The returned string will contain the sentence before the offset if the offset is inside a sentence and will contain the sentence before the sentence before the offset if the offset is not inside a sentence.

If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string is from the sentence end before the sentence end at or before the offset to the sentence end at or before the offset.

The returned string will contain the sentence before the offset if the offset is inside a sentence or if the offset is not inside a sentence.

If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start before the line start ar or before the offset to the line start ar or before the offset.

If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string is from the line end before the line end before the offset to the line end before the offset.

`text` :	an AtkText
`offset` :	position
`boundary_type` :	An AtkTextBoundary
`start_offset` :	the start offset of the returned string.
`end_offset` :	the end offset of the returned string.
Returns :	the text before `offset` bounded by the specified `boundary_type`.

atk_text_get_caret_offset ()

gint        atk_text_get_caret_offset       (AtkText *text);

Gets the offset position of the caret (cursor).

`text` :	an AtkText
Returns :	the offset position of the caret (cursor).

atk_text_get_character_extents ()

void        atk_text_get_character_extents  (AtkText *text,
                                             gint offset,
                                             gint *x,
                                             gint *y,
                                             gint *width,
                                             gint *height,
                                             AtkCoordType coords);

Given an offset, the x, y, width, and height values are filled appropriately.

`text` :	an AtkText
`offset` :	position
`x` :	x-position of character
`y` :	y-position of character
`width` :	width of character
`height` :	height of character
`coords` :	specify whether coordinates are relative to the screen or widget window

atk_text_get_run_attributes ()

AtkAttributeSet* atk_text_get_run_attributes
                                            (AtkText *text,
                                             gint offset,
                                             gint *start_offset,
                                             gint *end_offset);

Creates an AtkAttributeSet which consists of the attributes explicitly set at the position offset in the text. start_offset and end_offset are set to the start and end of the range around offset where the attributes are invariant. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

`text` :	an AtkText
`offset` :	the offset at which to get the attributes
`start_offset` :	the address to put the start offset of the range
`end_offset` :	the address to put the end offset of the range
Returns :	an AtkAttributeSet which contains the attributes explicitly set at `offset`. This AtkAttributeSet should be freed by a call to atk_attribute_set_free().

atk_text_get_default_attributes ()

AtkAttributeSet* atk_text_get_default_attributes
                                            (AtkText *text);

Creates an AtkAttributeSet which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

`text` :	an AtkText
Returns :	an AtkAttributeSet which contains the default values of attributes. at `offset`. This AtkAttributeSet should be freed by a call to atk_attribute_set_free().

atk_text_get_character_count ()

gint        atk_text_get_character_count    (AtkText *text);

Gets the character count.

`text` :	an AtkText
Returns :	the number of characters.

atk_text_get_offset_at_point ()

gint        atk_text_get_offset_at_point    (AtkText *text,
                                             gint x,
                                             gint y,
                                             AtkCoordType coords);

Gets the offset of the character located at coordinates x and y. x and y are interpreted as being relative to the screen or this widget's window depending on coords.

`text` :	an AtkText
`x` :	screen x-position of character
`y` :	screen y-position of character
`coords` :	specify whether coordinates are relative to the screen or widget window
Returns :	the offset to the character which is located at the specified `x` and `y` coordinates.

atk_text_get_n_selections ()

gint        atk_text_get_n_selections       (AtkText *text);

Gets the number of selected regions.

`text` :	an AtkText
Returns :	The number of selected regions, or -1 if a failure occurred.

atk_text_get_selection ()

gchar*      atk_text_get_selection          (AtkText *text,
                                             gint selection_num,
                                             gint *start_offset,
                                             gint *end_offset);

Gets the text from the specified selection.

`text` :	an AtkText
`selection_num` :	The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering.
`start_offset` :	passes back the start position of the selected region
`end_offset` :	passes back the end position of the selected region
Returns :	the selected text.

atk_text_add_selection ()

gboolean    atk_text_add_selection          (AtkText *text,
                                             gint start_offset,
                                             gint end_offset);

Adds a selection bounded by the specified offsets.

`text` :	an AtkText
`start_offset` :	the start position of the selected region
`end_offset` :	the end position of the selected region
Returns :	`TRUE` if success, `FALSE` otherwise

atk_text_remove_selection ()

gboolean    atk_text_remove_selection       (AtkText *text,
                                             gint selection_num);

Removes the specified selection.

`text` :	an AtkText
`selection_num` :	The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering.
Returns :	`TRUE` if success, `FALSE` otherwise

atk_text_set_selection ()

gboolean    atk_text_set_selection          (AtkText *text,
                                             gint selection_num,
                                             gint start_offset,
                                             gint end_offset);

Changes the start and end offset of the specified selection.

`text` :	an AtkText
`selection_num` :	The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering.
`start_offset` :	the new start position of the selection
`end_offset` :	the new end position of the selection
Returns :	`TRUE` if success, `FALSE` otherwise

atk_text_set_caret_offset ()

gboolean    atk_text_set_caret_offset       (AtkText *text,
                                             gint offset);

Sets the caret (cursor) position to the specified offset.

`text` :	an AtkText
`offset` :	position
Returns :	`TRUE` if success, `FALSE` otherwise.

atk_attribute_set_free ()

void        atk_attribute_set_free          (AtkAttributeSet *attrib_set);

Frees the memory used by an AtkAttributeSet, including all its AtkAttributes.

attrib_set : The AtkAttributeSet to free

atk_text_attribute_register ()

AtkTextAttribute atk_text_attribute_register
                                            (const gchar *name);

Associate name with a new AtkTextAttribute

`name` :	a name string
Returns :	an AtkTextAttribute associated with `name`

atk_text_attribute_get_name ()

G_CONST_RETURN gchar* atk_text_attribute_get_name
                                            (AtkTextAttribute attr);

Gets the name corresponding to the AtkTextAttribute

`attr` :	The AtkTextAttribute whose name is required
Returns :	a string containing the name; this string should not be freed

atk_text_attribute_for_name ()

AtkTextAttribute atk_text_attribute_for_name
                                            (const gchar *name);

Get the AtkTextAttribute type corresponding to a text attribute name.

`name` :	a string which is the (non-localized) name of an ATK text attribute.
Returns :	the AtkTextAttribute enumerated type corresponding to the specified name, or ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found.

atk_text_attribute_get_value ()

G_CONST_RETURN gchar* atk_text_attribute_get_value
                                            (AtkTextAttribute attr,
                                             gint index);

Gets the value for the index of the AtkTextAttribute

`attr` :	The AtkTextAttribute for which a value is required
`index` :	The index of the required value
Returns :	a string containing the value; this string should not be freed; NULL is returned if there are no values maintained for the attr value.

AtkText

Name

Synopsis

Description

Details

struct AtkText

struct AtkTextIface

enum AtkTextBoundary

struct AtkAttribute

AtkAttributeSet

enum AtkTextAttribute

atk_text_get_text ()

atk_text_get_character_at_offset ()

atk_text_get_text_after_offset ()

atk_text_get_text_at_offset ()

atk_text_get_text_before_offset ()

atk_text_get_caret_offset ()

atk_text_get_character_extents ()

atk_text_get_run_attributes ()

atk_text_get_default_attributes ()

atk_text_get_character_count ()

atk_text_get_offset_at_point ()

atk_text_get_n_selections ()

atk_text_get_selection ()

atk_text_add_selection ()

atk_text_remove_selection ()

atk_text_set_selection ()

atk_text_set_caret_offset ()

atk_attribute_set_free ()

atk_text_attribute_register ()

atk_text_attribute_get_name ()

atk_text_attribute_for_name ()

atk_text_attribute_get_value ()