Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Atk::Text Class Reference

A AtkText C++ wrapper class. More...

`#include <inti/atk/text.h>`

Inheritance diagram for Inti::Atk::Text:

List of all members.

## Public Member Functions

Accessors

- AtkText * atk_text () const
    Get a pointer to the AtkText structure.
- AtkTextIface * atk_text_iface () const
    Get a pointer to the AtkTextIface structure.
- operator AtkText * () const
    Conversion operator; safely converts a Text to an AtkText pointer.
- String get_text (int start_offset, int end_offset) const
    Gets the specified text.
- G::Unichar get_character_at_offset (int offset) const
    Gets the character at the specified offset.
- String get_text_after_offset (int offset, TextBoundary boundary_type, int *start_offset, int *end_offset) const
    Gets the specified text.
- String get_text_at_offset (int offset, TextBoundary boundary_type, int *start_offset, int *end_offset) const
    Gets the specified text.
- String get_text_before_offset (int offset, TextBoundary boundary_type, int *start_offset, int *end_offset) const
    Gets the specified text.
- int get_caret_offset () const
    Returns the offset position of the caret (cursor).
- void get_character_extents (int offset, int *x, int *y, int *width, int *height, CoordType coords) const
    Given an offset, the x, y, width, and height values are filled appropriately.
- std::vector< Attribute > get_run_attributes (int offset, int *start_offset, int *end_offset) const
    Gets a list which consists of the attributes explicitly set at the position offset in the text.
- std::vector< Attribute > get_default_attributes () const
    Gets a list which consists of the default values of attributes for the text.
- int get_character_count () const
    Gets the character count for the text.
- int get_offset_at_point (int x, int y, CoordType coords) const
    Gets the offset of the character located at coordinates x and y.
- int get_n_selections () const
    Gets the number of selected regions.
- String get_selection (int selection_num, int *start_offset, int *end_offset) const
    Gets the text from the specified selection.

Methods

- bool add_selection (int start_offset, int end_offset)
    Adds the selection bounded by the specified offsets.
- bool remove_selection (int selection_num)
    Removes the specified selection.
- bool set_selection (int selection_num, int start_offset, int end_offset)
    Changes the start and end offset of the specified selection.
- bool set_caret_offset (int offset)
    Sets the caret (cursor) position to the specified offset.

Signal Proxies

- const TextChangedSignalProxy sig_text_changed ()
    Connect to the text_changed_signal; emitted when text is inserted or deleted.
- const TextCaretMovedSignalProxy sig_text_caret_moved ()
    Connect to the text_caret_moved_signal; emitted when the text caret is moved.
- const TextSelectionChangedSignalProxy sig_text_selection_changed ()
    Connect to the text_selection_changed_signal; emitted when the text selection changes.
- const TextAttributesChangedSignalProxy sig_text_attributes_changed ()
    Connect to the text_attributes_changed_signal; emitted when the text attributes change.

## Protected Member Functions

Constructors

- virtual ~Text ()=0
    Destructor.

Signal Handlers

- virtual void on_text_changed (int position, int length)
    Called when text is inserted or deleted.
- virtual void on_text_caret_moved (int location)
    Called when the text caret is moved.
- virtual void on_text_selection_changed ()
    Called when the text selection changes.
- virtual void on_text_attributes_changed ()
    Called when the text attributes change.

## Detailed Description

A AtkText C++ wrapper class.

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 Text interface should be used to expose the text content. In the case of editable text content, EditableText (a subtype of the Text interface) should be implemented instead.

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.

## Member Function Documentation

bool Inti::Atk::Text::add_selection | ( | int | start_offset,
|  | int | end_offset
| ) |

Adds the selection bounded by the specified offsets.

Parameters:

  start_offset | The start position of the selected region.
  end_offset | The end position of the selected region.

Returns:
  true if successful, false otherwise.

G::Unichar Inti::Atk::Text::get_character_at_offset | ( | int | offset | ) | const

Gets the character at the specified offset.

Parameters:

  offset | The character position.

Returns:
  The character at offset.

int Inti::Atk::Text::get_character_count | ( |  | ) | const

Gets the character count for the text.

Returns:
  The number of characters in the text.

void Inti::Atk::Text::get_character_extents | ( | int | offset,
|  | int * | x,
|  | int * | y,
|  | int * | width,
|  | int * | height,
|  | CoordType | coords
| ) | const

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

Parameters:

  offset | A character position.
  x | The location for the x-position of the character at position, or null.
  y | The location for the y-position of the character at position, or null.
  width | The location for the width of the character at position, or null.
  height | The location for the height of the character at position, or null.
  coords | Specify whether coordinates are relative to the screen or the widget window.

std::vector<Attribute> Inti::Atk::Text::get_default_attributes | ( |  | ) | const

Gets a list which consists of the default values of attributes for the text.

Returns:
  A vector of Attribute which contains the default values of the attributes at offset.

See the enum Atk::TextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned.

int Inti::Atk::Text::get_n_selections | ( |  | ) | const

Gets the number of selected regions.

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

int Inti::Atk::Text::get_offset_at_point | ( | int | x,
|  | int | y,
|  | CoordType | coords
| ) | const

Gets the offset of the character located at coordinates x and y.

Parameters:

  x | The x-position of a character.
  y | The y-position of a character.
  coords | Specify whether the 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.

x and y are interpreted as being relative to the screen or this widget's window, depending on coords.

std::vector<Attribute> Inti::Atk::Text::get_run_attributes | ( | int | offset,
|  | int * | start_offset,
|  | int * | end_offset
| ) | const

Gets a list which consists of the attributes explicitly set at the position offset in the text.

Parameters:

  offset | The offset at which to get the attributes.
  start_offset | The address to put the start offset of the range, or null.
  end_offset | The address to put the end offset of the range, or null.

Returns:
  A vector of Attribute which contains the attributes explicitly set at offset.

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 Atk::TextAttribute for the types of text attributes that can be returned. Note that other attributes may also be returned.

String Inti::Atk::Text::get_selection | ( | int | selection_num,
|  | int * | start_offset,
|  | int * | end_offset
| ) | const

Gets the text from the specified selection.

Parameters:

  selection_num | The selection number.
  start_offset | The location for the start position of the selected region.
  end_offset | The location for the end position of the selected region.

Returns:
  The selected text.

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.

String Inti::Atk::Text::get_text | ( | int | start_offset,
|  | int | end_offset
| ) | const

Gets the specified text.

Parameters:

  start_offset | The start position.
  end_offset | The end position.

Returns:
  The text from start_offset up to, but not including end_offset.

String Inti::Atk::Text::get_text_after_offset | ( | int | offset,
|  | TextBoundary | boundary_type,
|  | int * | start_offset,
|  | int * | end_offset
| ) | const

Gets the specified text.

Parameters:

  offset | The position
  boundary_type | A TextBoundary.
  start_offset | The location for the start offset of the returned string.
  end_offset | The location for the end offset of the returned string.

Returns:
  The text after offset bounded by the specified boundary_type.

If boundary_type is TEXT_BOUNDARY_CHAR the character after the offset is returned.

If boundary_type is 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 boundary_type is 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 boundary_type is 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 boundary_type is 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 boundary_type is TEXT_BOUNDARY_LINE_START the returned string is from the line start after the offset to the next line start.

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

String Inti::Atk::Text::get_text_at_offset | ( | int | offset,
|  | TextBoundary | boundary_type,
|  | int * | start_offset,
|  | int * | end_offset
| ) | const

Gets the specified text.

Parameters:

  offset | The position
  boundary_type | A TextBoundary.
  start_offset | The location for the start offset of the returned string.
  end_offset | The location for the end offset of the returned string.

Returns:
  The text after offset bounded by the specified boundary_type.

If boundary_type is TEXT_BOUNDARY_CHAR the character at the offset is returned.

If boundary_type is 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 boundary_type is 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 boundary_typee is 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 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 boundary_type is 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 boundary_type is TEXT_BOUNDARY_LINE_END the returned string is from the line end before the offset to the line end at or after the offset.

String Inti::Atk::Text::get_text_before_offset | ( | int | offset,
|  | TextBoundary | boundary_type,
|  | int * | start_offset,
|  | int * | end_offset
| ) | const

Gets the specified text.

Parameters:

  offset | The position
  boundary_type | A TextBoundary.
  start_offset | The location for the start offset of the returned string.
  end_offset | The location for the end offset of the returned string.

Returns:
  The text after offset bounded by the specified boundary_type.

If the boundary_type is TEXT_BOUNDARY_CHAR the character before the offset is returned.

If boundary_type is 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 boundary_type is 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 boundary_type is 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 boundary_type is 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 boundary_type is TEXT_BOUNDARY_LINE_START the returned string is from the line start before the line start at or before the offset to the line start ar or before the offset.

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

virtual void Inti::Atk::Text::on_text_caret_moved | ( | int | location | ) | `[protected, virtual]`

Called when the text caret is moved.

Parameters:

  location | The new position of the text caret.

virtual void Inti::Atk::Text::on_text_changed | ( | int | position,
|  | int | length
| ) | `[protected, virtual]`

Called when text is inserted or deleted.

Parameters:

  position | The position of the insertion or deletion.
  length | The length of the text inserted or deleted.

bool Inti::Atk::Text::remove_selection | ( | int | selection_num | ) |

Removes the specified selection.

Parameters:

  selection_num | The selection number.

Returns:
  true if successful, false otherwise.

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.

bool Inti::Atk::Text::set_caret_offset | ( | int | offset | ) |

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

Parameters:

  offset | A character position.

Returns:
  true if successful, false otherwise.

bool Inti::Atk::Text::set_selection | ( | int | selection_num,
|  | int | start_offset,
|  | int | end_offset
| ) |

Changes the start and end offset of the specified selection.

Parameters:

  selection_num | The selection number.
  start_offset | The new start position of the selection.
  end_offset | The new end position of the selection.

Returns:
  true if successful, false otherwise.

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.

The documentation for this class was generated from the following file:

- text.h

Main Page - Footer