Next: , Previous: AtkTable, Up: Top

23 AtkText

The ATK interface implemented by components with text content.

23.1 Overview

<atk-text> should be implemented by <atk-objects> on behalf of widgets that have text content which is either attributed or otherwise non-trivial. <atk-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-editable-text> (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.

23.2 Usage

— Class: <atk-text>

Derives from <ginterface>.

This class defines no direct slots.

— Signal on <atk-text>: text-changed (arg0 <gint>) (arg1 <gint>)

The "text-changed" signal is emitted when the text of the object which implements the AtkText 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

— Signal on <atk-text>: text-caret-moved (arg0 <gint>)

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

— Signal on <atk-text>: text-selection-changed

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

— Signal on <atk-text>: text-attributes-changed

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

— Function: atk-text-get-text (self <atk-text>) (start_offset int) (end_offset int) ⇒  (ret mchars)
— Method: get-text

Gets the specified text.

text
an <atk-text>
start-offset
start position
end-offset
end position
ret
the text from start-offset up to, but not including end-offset.
— Function: atk-text-get-character-at-offset (self <atk-text>) (offset int) ⇒  (ret unsigned-int32)
— Method: get-character-at-offset

Gets the specified text.

text
an <atk-text>
offset
position
ret
the character at offset.
— Function: atk-text-get-text-after-offset (self <atk-text>) (offset int) (boundary_type <atk-text-boundary>) ⇒  (ret mchars) (start_offset int) (end_offset int)
— Method: get-text-after-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 <atk-text>
offset
position
boundary-type
An <atk-text-boundary>
start-offset
the start offset of the returned string
end-offset
the offset of the first character after the returned substring
ret
the text after offset bounded by the specified boundary-type.
— Function: atk-text-get-text-at-offset (self <atk-text>) (offset int) (boundary_type <atk-text-boundary>) ⇒  (ret mchars) (start_offset int) (end_offset int)
— Method: get-text-at-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 <atk-text>
offset
position
boundary-type
An <atk-text-boundary>
start-offset
the start offset of the returned string
end-offset
the offset of the first character after the returned substring
ret
the text at offset bounded by the specified boundary-type.
— Function: atk-text-get-text-before-offset (self <atk-text>) (offset int) (boundary_type <atk-text-boundary>) ⇒  (ret mchars) (start_offset int) (end_offset int)
— Method: get-text-before-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 <atk-text>
offset
position
boundary-type
An <atk-text-boundary>
start-offset
the start offset of the returned string
end-offset
the offset of the first character after the returned substring
ret
the text before offset bounded by the specified boundary-type.
— Function: atk-text-get-caret-offset (self <atk-text>) ⇒  (ret int)
— Method: get-caret-offset

Gets the offset position of the caret (cursor).

text
an <atk-text>
ret
the offset position of the caret (cursor).
— Function: atk-text-get-character-extents (self <atk-text>) (offset int) (coords <atk-coord-type>) ⇒  (x int) (y int) (width int) (height int)
— Method: get-character-extents

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

text
an <atk-text>
offset
The offset of the text character for which bounding information is required.
x
Pointer for the x cordinate of the bounding box
y
Pointer for the y cordinate of the bounding box
width
Pointer for the width of the bounding box
height
Pointer for the height of the bounding box
coords
specify whether coordinates are relative to the screen or widget window
— Function: atk-text-get-character-count (self <atk-text>) ⇒  (ret int)
— Method: get-character-count

Gets the character count.

text
an <atk-text>
ret
the number of characters.
— Function: atk-text-get-offset-at-point (self <atk-text>) (x int) (y int) (coords <atk-coord-type>) ⇒  (ret int)
— Method: get-offset-at-point

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 <atk-text>
x
screen x-position of character
y
screen y-position of character
coords
specify whether coordinates are relative to the screen or widget window
ret
the offset to the character which is located at the specified x and y coordinates.
— Function: atk-text-get-n-selections (self <atk-text>) ⇒  (ret int)
— Method: get-n-selections

Gets the number of selected regions.

text
an <atk-text>
ret
The number of selected regions, or -1 if a failure occurred.
— Function: atk-text-get-selection (self <atk-text>) (selection_num int) ⇒  (ret mchars) (start_offset int) (end_offset int)
— Method: get-selection

Gets the text from the specified selection.

text
an <atk-text>
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 (e.g. offset immediately past) the selected region
ret
the selected text.
— Function: atk-text-add-selection (self <atk-text>) (start_offset int) (end_offset int) ⇒  (ret bool)
— Method: add-selection

Adds a selection bounded by the specified offsets.

text
an <atk-text>
start-offset
the start position of the selected region
end-offset
the offset of the first character after the selected region.
ret
‘#t’ if success, ‘#f’ otherwise
— Function: atk-text-remove-selection (self <atk-text>) (selection_num int) ⇒  (ret bool)
— Method: remove-selection

Removes the specified selection.

text
an <atk-text>
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.
ret
‘#t’ if success, ‘#f’ otherwise
— Function: atk-text-set-selection (self <atk-text>) (selection_num int) (start_offset int) (end_offset int) ⇒  (ret bool)
— Method: set-selection

Changes the start and end offset of the specified selection.

text
an <atk-text>
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
ret
‘#t’ if success, ‘#f’ otherwise
— Function: atk-text-set-caret-offset (self <atk-text>) (offset int) ⇒  (ret bool)
— Method: set-caret-offset

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

text
an <atk-text>
offset
position
ret
‘#t’ if success, ‘#f’ otherwise.
— Function: atk-text-attribute-get-name (attr <atk-text-attribute>) ⇒  (ret mchars)

Gets the name corresponding to the <atk-text-attribute>

attr
The <atk-text-attribute> whose name is required
ret
a string containing the name; this string should not be freed
— Function: atk-text-attribute-for-name (name mchars) ⇒  (ret <atk-text-attribute>)

Get the <atk-text-attribute> type corresponding to a text attribute name.

name
a string which is the (non-localized) name of an ATK text attribute.
ret
the <atk-text-attribute> enumerated type corresponding to the specified name, or <atk-text-attribute-invalid> if no matching text attribute is found.
— Function: atk-text-attribute-get-value (attr <atk-text-attribute>) (index_ int) ⇒  (ret mchars)

Gets the value for the index of the <atk-text-attribute>

attr
The <atk-text-attribute> for which a value is required
index
The index of the required value
ret
a string containing the value; this string should not be freed; NULL is returned if there are no values maintained for the attr value.