atk.Text

atk.Text
Prev	The atk Class Reference	Next

atk.Text — the ATK interface implemented by components with text content.

Synopsis

class atk.Text(gobject.GInterface):
    def get_text(start_offset, end_offset)
    def get_character_at_offset(offset)
    def get_text_after_offset(offset, boundary_type)
    def get_text_at_offset(offset, boundary_type)
    def get_text_before_offset(offset, boundary_type)
    def get_caret_offset()
    def get_character_extents(offset, coords)
    def get_run_attributes(offset)
    def get_default_attributes()
    def get_character_count()
    def get_offset_at_point(x, y, coords)
    def get_n_selections()
    def get_selection(selection_num)
    def add_selection(start_offset, end_offset)
    def remove_selection(selection_num)
    def set_selection(selection_num, start_offset, end_offset)
    def set_caret_offset(offset)
    def get_range_extents(start_offset, end_offset, coord_type)
    def get_bounded_ranges(rect, coord_type, x_clip_type, y_clip_type)

Functions

    def atk.text_attribute_get_name(attr)
    def atk.text_attribute_get_value(attr, index)
    def atk.text_attribute_register(name)
    def atk.text_attribute_for_name(name)

atk.Text Signal Prototypes

"text-attributes-changed"	`def callback(atktext, user_param1, ...)`
"text-caret-moved"	`def callback(atktext, position, user_param1, ...)`
"text-changed"	`def callback(atktext, position, length, user_param1, ...)`
"text-selection-changed"	`def callback(atktext, user_param1, ...)`

Description

atk.Text should be implemented by atk.Object objects on behalf of widgets that have text content which is either attributed or otherwise non-trivial. atk.Object objects whose text content is simple, unattributed, and very brief may expose that content via atk.Object.get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the atk.Text interface should be used to expose the text content. In the case of editable text content, atk.EditableText (a subtype of the atk.Text interface) should be implemented instead.

atk.Text provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures.

Methods

atk.Text.get_text

    def get_text(start_offset, end_offset)

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

Gets the specified text.

atk.Text.get_character_at_offset

    def get_character_at_offset(offset)

`offset` :	position
Returns :	the character at `offset`.

Gets the specified text.

atk.Text.get_text_after_offset

    def get_text_after_offset(offset, boundary_type)

`offset` :	position
`boundary_type` :	one of the Atk Text Boundary Constants
Returns :	a 3-tuple containing the text after `offset` bounded by the specified `boundary_type`, the start offset of the returned string and the offset of the first character after the returned substring.

Gets the specified text.

If the boundary_type is 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.

atk.Text.get_text_at_offset

    def get_text_at_offset(offset, boundary_type)

`offset` :	position
`boundary_type` :	one of the Atk Text Boundary Constants
Returns :	a 3-tuple containing the text at `offset` bounded by the specified `boundary_type`, the start offset of the returned string and the offset of the first character after the returned substring.

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.

atk.Text.get_text_before_offset

    def get_text_before_offset(offset, boundary_type)

`offset` :	position
`boundary_type` :	one of the Atk Text Boundary Constants
Returns :	a 3-tuple containing the text before `offset` bounded by the specified `boundary_type`, the start offset of the returned string and the offset of the first character after the returned substring.

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.

atk.Text.get_caret_offset

    def get_caret_offset()

Returns :

the offset position of the caret (cursor).

Gets the offset position of the caret (cursor).

atk.Text.get_character_extents

    def get_character_extents(offset, coords)

`offset` :	The offset of the text character for which bounding information is required.
`coords` :	specify whether coordinates are relative to the screen or widget window - one of the Atk Coord Type Constants
Returns :	a 4-tuple containing the x, y position and width and height of the bounding box.

Get the bounding box containing the glyph representing the character at a particular text offset.

atk.Text.get_run_attributes

    def get_run_attributes(offset)

`offset` :	the offset at which to get the attributes
`start_offset` :	the address to put
`end_offset` :	the address to put
Returns :	a 3-tuple containing an attribute set tuple, the start offset of the range and the end offset of the range. The attribute set tuple contains a 2-tuple of (name, value) strings for each attribute explicitly set at `offset`.

Creates a 3=tuple containing an attribute set (which consists of the attributes explicitly set at the position offset in the text), the start and end of the range around offset where the attributes are invariant. Note that the end offset is the offset of the first character after the range. See the Atk Text Attribute Constants for types of text attributes that can be returned. Note that other attributes may also be returned.

atk.Text.get_default_attributes

    def get_default_attributes()

Returns :

a tuple containing the attribute set which contains the default values of attributes. The attribute set tuple contains a 2-tuple of (name, value) strings for each attribute.

Creates a tuple containing an attribute set which consists of the default values of attributes for the text. The attribute set tuple contains a 2-tuple of (name, value) strings for each attribute See the Atk Text Attribute Constants for types of text attributes that can be returned. Note that other attributes may also be returned.

atk.Text.get_character_count

    def get_character_count()

Returns :

the number of characters.

Gets the character count.

atk.Text.get_offset_at_point

    def get_offset_at_point(x, y, coords)

`x` :	screen x-position of character
`y` :	screen y-position of character
`coords` :	specify whether coordinates are relative to the screen or widget window - one of the Atk Coord Type Constants
Returns :	the offset to the character which is located at the specified `x` and `y` coordinates.

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.

atk.Text.get_n_selections

    def get_n_selections()

Returns :

The number of selected regions, or -1 if a failure occurred.

Gets the number of selected regions.

atk.Text.get_selection

    def get_selection(selection_num)

`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 :	a 3-tuple containing the selected text, the start position of the selected region and the end position of (e.g. offset immediately past) the selected region.

Gets the text from the specified selection.

atk.Text.add_selection

    def add_selection(start_offset, end_offset)

`start_offset` :	the start position of the selected region
`end_offset` :	the offset of the first character after the selected region.
Returns :	`TRUE` if success, `FALSE` otherwise

Adds a selection bounded by the specified offsets.

atk.Text.remove_selection

    def remove_selection(selection_num)

`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

Removes the specified selection.

atk.Text.set_selection

    def set_selection(selection_num, start_offset, end_offset)

`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 (e.g. offset immediately past) the selection
Returns :	`TRUE` if success, `FALSE` otherwise

Changes the start and end offset of the specified selection.

atk.Text.set_caret_offset

    def set_caret_offset(offset)

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

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

atk.Text.get_range_extents

    def get_range_extents(start_offset, end_offset, coord_type)

`start_offset` :	The offset of the first text character for which boundary information is required.
`end_offset` :	The offset of the text character after the last character for which boundary information is required.
`coord_type` :	Specify whether coordinates are relative to the screen or widget window - one of the Atk Coord Type Constants.
Returns :	a `atk.Rectangle` containing the extents of the range.

Get the bounding box for text within the specified range.

atk.Text.get_bounded_ranges

    def get_bounded_ranges(rect, coord_type, x_clip_type, y_clip_type)

`rect` :	An `atk.Rectangle` giving the dimensions of the bounding box.
`coord_type` :	Specify whether coordinates are relative to the screen or widget window - one of the Atk Coord Type Constants.
`x_clip_type` :	Specify the horizontal clip type - one of the Atk Text Clip Type Constants.
`y_clip_type` :	Specify the vertical clip type - one of the Atk Text Clip Type Constants.
Returns :	a list of text ranges. The list contains a 4-tuple for each text range. The 4-tuple contains a `atk.Rectangle` bounding the text range, the start and end offsets of the range and the text in the range.

Get the ranges of text in the specified bounding box.

Functions

atk.text_attribute_get_name

    def atk.text_attribute_get_name(attr)

`attr` :	a text attribute (one of the Atk Text Attribute Constants) whose name is required
Returns :	a string containing the name

Gets the name corresponding to attr.

atk.text_attribute_get_value

    def atk.text_attribute_get_value(attr, index)

`attr` :	a text attribute (one of the Atk Text Attribute Constants) whose name is required
`index` :	The index of the required value
Returns :	a string containing the value. `None` is returned if there are no values maintained for the `attr` value.

Gets the value for the index of the text attribute specified by attr.

atk.text_attribute_register

    def atk.text_attribute_register(name)

`name` :	a name string
Returns :	a new one of the Atk Text Attribute Constants that is associated with name

Associate name with a new text attribute.

atk.text_attribute_for_name

    def atk.text_attribute_for_name(name)

`name` :	a string which is the (non-localized) name of an ATK text attribute.
Returns :	the text attribute (one of the Atk Text Attribute Constants) corresponding to the specified name, or `atk.TEXT_ATTRIBUTE_INVALID` if no matching text attribute is found.

Get the text attribute type corresponding to a text attribute name specified by name.

Signals

The "text-attributes-changed" atk.Text Signal

    def callback(atktext, user_param1, ...)

`atktext` :	the object which received the signal.
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "text-attributes-changed" signal is emitted when the text attributes of the text of an object which implements atk.Text changes.

The "text-caret-moved" atk.Text Signal

    def callback(atktext, position, user_param1, ...)

`atktext` :	the object which received the signal.
`position` :	The new position of the text caret.
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "text-caret-moved" signal is emitted when the caret position of the text of an object which implements atk.Text changes.

The "text-changed" atk.Text Signal

    def callback(atktext, position, length, user_param1, ...)

`atktext` :	the object which received the signal.
`position` :	The position of the insertion or deletion.
`length` :	The length of text inserted or deleted.
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "text-changed" signal is emitted when the text of the object which implements the atk.Text interface changes, This signal will have a detail which is either "insert" or "delete" which identifies whether the text change was an insertion or a deletion

The "text-selection-changed" atk.Text Signal

    def callback(atktext, user_param1, ...)

`atktext` :	the object which received the signal.
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "text-selection-changed" signal is emitted when the selected text of an object which implements atk.Text changes.

Prev	Up	Next
atk.Table	Home	atk.Value