atkmm 2.28.3
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Atk::Text Class Reference

The ATK interface implemented by components with text content. More...

#include <atkmm/text.h>

Inheritance diagram for Atk::Text:
Inheritance graph
[legend]

Public Types

typedef AtkTextRectangle Rectangle
 

Public Member Functions

 Text (Text && src) noexcept
 
Textoperator= (Text && src) noexcept
 
 ~Text () noexcept override
 
AtkText * gobj ()
 Provides access to the underlying C GObject. More...
 
const AtkText * gobj () const
 Provides access to the underlying C GObject. More...
 
Glib::ustring get_text (int start_offset, int end_offset) const
 Gets the specified text. More...
 
gunichar get_character_at_offset (int offset) const
 Gets the specified text. More...
 
Glib::ustring get_text_after_offset (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 Gets the specified text. More...
 
Glib::ustring get_text_at_offset (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 Gets the specified text. More...
 
Glib::ustring get_text_before_offset (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 Gets the specified text. More...
 
Glib::ustring get_string_at_offset (int offset, TextGranularity granularity, int & start_offset, int & end_offset)
 Gets a portion of the text exposed through an Atk::Text according to a given offset and a specific granularity, along with the start and end offsets defining the boundaries of such a portion of text. More...
 
int get_caret_offset () const
 Gets the offset position of the caret (cursor). More...
 
void get_character_extents (int offset, int & x, int & y, int & width, int & height, CoordType coords) const
 Get the bounding box containing the glyph representing the character at a particular text offset. More...
 
AttributeSet get_run_attributes (int offset, int & start_offset, int & end_offset) const
 Creates an Atk::AttributeSet which consists of the attributes explicitly set at the position offset in the text. More...
 
AttributeSet get_default_attributes () const
 Creates an Atk::AttributeSet which consists of the default values of attributes for the text. More...
 
int get_character_count () const
 Gets the character count. More...
 
int get_offset_at_point (int x, int y, CoordType coords) const
 Gets the offset of the character located at coordinates x and y. More...
 
int get_n_selections () const
 Gets the number of selected regions. More...
 
Glib::ustring get_selection (int selection_num, int & start_offset, int & end_offset) const
 Gets the text from the specified selection. More...
 
bool add_selection (int start_offset, int end_offset)
 Adds a selection bounded by the specified offsets. More...
 
bool remove_selection (int selection_num)
 Removes the specified selection. More...
 
bool set_selection (int selection_num, int start_offset, int end_offset)
 Changes the start and end offset of the specified selection. More...
 
bool set_caret_offset (int offset)
 Sets the caret (cursor) position to the specified offset. More...
 
void get_range_extents (int start_offset, int end_offset, CoordType coord_type, Rectangle & rect)
 Get the bounding box for text within the specified range. More...
 
AtkTextRange ** get_bounded_ranges (const Rectangle & rect, CoordType coord_type, TextClipType x_clip_type, TextClipType y_clip_type)
 Get the ranges of text in the specified bounding box. More...
 
Glib::SignalProxy< void, int, int > signal_text_changed ()
 
Glib::SignalProxy< void, int > signal_text_caret_moved ()
 
Glib::SignalProxy< void > signal_text_selection_changed ()
 
Glib::SignalProxy< void > signal_text_attributes_changed ()
 

Static Public Member Functions

static void add_interface (GType gtype_implementer)
 
static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 

Protected Member Functions

 Text ()
 You should derive from this class to use it. More...
 
virtual Glib::ustring get_text_vfunc (int start_offset, int end_offset) const
 
virtual gunichar get_character_at_offset_vfunc (int offset) const
 
virtual Glib::ustring get_text_after_offset_vfunc (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 
virtual Glib::ustring get_text_at_offset_vfunc (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 
virtual Glib::ustring get_text_before_offset_vfunc (int offset, TextBoundary boundary_type, int & start_offset, int & end_offset) const
 
virtual int get_caret_offset_vfunc () const
 
virtual void get_character_extents_vfunc (int offset, int & x, int & y, int & width, int & height, CoordType coords) const
 
virtual AtkAttributeSet * get_run_attributes_vfunc (int offset, int & start_offset, int & end_offset) const
 
virtual AtkAttributeSet * get_default_attributes_vfunc () const
 
virtual int get_character_count_vfunc () const
 
virtual int get_offset_at_point_vfunc (int x, int y, CoordType coords) const
 
virtual int get_n_selections_vfunc () const
 
virtual Glib::ustring get_selection_vfunc (int selection_num, int & start_offset, int & end_offset) const
 
virtual bool add_selection_vfunc (int start_offset, int end_offset)
 
virtual bool remove_selection_vfunc (int selection_num)
 
virtual bool set_selection_vfunc (int selection_num, int start_offset, int end_offset)
 
virtual bool set_caret_offset_vfunc (int offset)
 
virtual void on_text_changed (int position, int length)
 This is a default handler for the signal signal_text_changed(). More...
 
virtual void on_text_caret_moved (int location)
 This is a default handler for the signal signal_text_caret_moved(). More...
 
virtual void on_text_selection_changed ()
 This is a default handler for the signal signal_text_selection_changed(). More...
 
virtual void on_text_attributes_changed ()
 This is a default handler for the signal signal_text_attributes_changed(). More...
 

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Atk::Textwrap (AtkText * object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Detailed Description

The ATK interface implemented by components with text content.

This 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, this 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.

Member Typedef Documentation

◆ Rectangle

typedef AtkTextRectangle Atk::Text::Rectangle

Constructor & Destructor Documentation

◆ Text() [1/2]

Atk::Text::Text ( )
protected

You should derive from this class to use it.

◆ Text() [2/2]

Atk::Text::Text ( Text &&  src)
noexcept

◆ ~Text()

Atk::Text::~Text ( )
overridenoexcept

Member Function Documentation

◆ add_interface()

static void Atk::Text::add_interface ( GType  gtype_implementer)
static

◆ add_selection()

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

Adds a selection bounded by the specified offsets.

Parameters
start_offsetThe start position of the selected region.
end_offsetThe offset of the first character after the selected region.
Returns
true if success, false otherwise.

◆ add_selection_vfunc()

virtual bool Atk::Text::add_selection_vfunc ( int  start_offset,
int  end_offset 
)
protectedvirtual

◆ get_bounded_ranges()

AtkTextRange ** Atk::Text::get_bounded_ranges ( const Rectangle rect,
CoordType  coord_type,
TextClipType  x_clip_type,
TextClipType  y_clip_type 
)

Get the ranges of text in the specified bounding box.

Since atkmm 1.3:
Parameters
rectAn AtkTextRectangle giving the dimensions of the bounding box.
coord_typeSpecify whether coordinates are relative to the screen or widget window.
x_clip_typeSpecify the horizontal clip type.
y_clip_typeSpecify the vertical clip type.
Returns
Array of AtkTextRange. The last element of the array returned by this function will be nullptr.

◆ get_caret_offset()

int Atk::Text::get_caret_offset ( ) const

Gets the offset position of the caret (cursor).

Returns
The offset position of the caret (cursor).

◆ get_caret_offset_vfunc()

virtual int Atk::Text::get_caret_offset_vfunc ( ) const
protectedvirtual

◆ get_character_at_offset()

gunichar Atk::Text::get_character_at_offset ( int  offset) const

Gets the specified text.

Parameters
offsetPosition.
Returns
The character at offset.

◆ get_character_at_offset_vfunc()

virtual gunichar Atk::Text::get_character_at_offset_vfunc ( int  offset) const
protectedvirtual

◆ get_character_count()

int Atk::Text::get_character_count ( ) const

Gets the character count.

Returns
The number of characters.

◆ get_character_count_vfunc()

virtual int Atk::Text::get_character_count_vfunc ( ) const
protectedvirtual

◆ get_character_extents()

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

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

Parameters
offsetThe offset of the text character for which bounding information is required.
xPointer for the x cordinate of the bounding box.
yPointer for the y cordinate of the bounding box.
widthPointer for the width of the bounding box.
heightPointer for the height of the bounding box.
coordsSpecify whether coordinates are relative to the screen or widget window.

◆ get_character_extents_vfunc()

virtual void Atk::Text::get_character_extents_vfunc ( int  offset,
int &  x,
int &  y,
int &  width,
int &  height,
CoordType  coords 
) const
protectedvirtual

◆ get_default_attributes()

AttributeSet Atk::Text::get_default_attributes ( ) const

Creates an Atk::AttributeSet 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.

Returns
An Atk::AttributeSet which contains the default values of attributes. at offset.

◆ get_default_attributes_vfunc()

virtual AtkAttributeSet * Atk::Text::get_default_attributes_vfunc ( ) const
protectedvirtual

◆ get_n_selections()

int Atk::Text::get_n_selections ( ) const

Gets the number of selected regions.

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

◆ get_n_selections_vfunc()

virtual int Atk::Text::get_n_selections_vfunc ( ) const
protectedvirtual

◆ get_offset_at_point()

int 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.

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

Parameters
xScreen x-position of character.
yScreen y-position of character.
coordsSpecify 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.

◆ get_offset_at_point_vfunc()

virtual int Atk::Text::get_offset_at_point_vfunc ( int  x,
int  y,
CoordType  coords 
) const
protectedvirtual

◆ get_range_extents()

void Atk::Text::get_range_extents ( int  start_offset,
int  end_offset,
CoordType  coord_type,
Rectangle rect 
)

Get the bounding box for text within the specified range.

Since atkmm 1.3:
Parameters
start_offsetThe offset of the first text character for which boundary information is required.
end_offsetThe offset of the text character after the last character for which boundary information is required.
coord_typeSpecify whether coordinates are relative to the screen or widget window.
rectA pointer to a AtkTextRectangle which is filled in by this function.

◆ get_run_attributes()

AttributeSet Atk::Text::get_run_attributes ( int  offset,
int &  start_offset,
int &  end_offset 
) const

Creates an Atk::AttributeSet 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.

Parameters
offsetThe offset at which to get the attributes.
start_offsetThe address to put the start offset of the range.
end_offsetThe address to put the end offset of the range.
Returns
An Atk::AttributeSet which contains the attributes explicitly set at offset.

◆ get_run_attributes_vfunc()

virtual AtkAttributeSet * Atk::Text::get_run_attributes_vfunc ( int  offset,
int &  start_offset,
int &  end_offset 
) const
protectedvirtual

◆ get_selection()

Glib::ustring Atk::Text::get_selection ( int  selection_num,
int &  start_offset,
int &  end_offset 
) const

Gets the text from the specified selection.

Parameters
selection_numThe 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_offsetPasses back the start position of the selected region.
end_offsetPasses back the end position of (e.g. offset immediately past) the selected region.
Returns
A newly allocated string containing the selected text.

◆ get_selection_vfunc()

virtual Glib::ustring Atk::Text::get_selection_vfunc ( int  selection_num,
int &  start_offset,
int &  end_offset 
) const
protectedvirtual

◆ get_string_at_offset()

Glib::ustring Atk::Text::get_string_at_offset ( int  offset,
TextGranularity  granularity,
int &  start_offset,
int &  end_offset 
)

Gets a portion of the text exposed through an Atk::Text according to a given offset and a specific granularity, along with the start and end offsets defining the boundaries of such a portion of text.

If granularity is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned.

If granularity is ATK_TEXT_GRANULARITY_WORD 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 granularity is ATK_TEXT_GRANULARITY_SENTENCE 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 granularity is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset.

If granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset.

Since atkmm 2.10:
Parameters
offsetPosition.
granularityAn Atk::TextGranularity.
start_offsetThe start offset of the returned string, or -1 if an error has occurred (e.g. invalid offset, not implemented).
end_offsetThe offset of the first character after the returned string, or -1 if an error has occurred (e.g. invalid offset, not implemented).
Returns
A newly allocated string containing the text at the offset bounded by the specified granularity. Returns nullptr if the offset is invalid or no implementation is available.

◆ get_text()

Glib::ustring Atk::Text::get_text ( int  start_offset,
int  end_offset 
) const

Gets the specified text.

Parameters
start_offsetStart position.
end_offsetEnd position, or -1 for the end of the string.
Returns
A newly allocated string containing the text from start_offset up to, but not including end_offset.

◆ get_text_after_offset()

Glib::ustring Atk::Text::get_text_after_offset ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const

Gets the specified text.

Deprecated: 2.9.3: Please use get_string_at_offset() instead.

Deprecated:
Use get_string_at_offset() instead.
Parameters
offsetPosition.
boundary_typeAn Atk::TextBoundary.
start_offsetThe start offset of the returned string.
end_offsetThe offset of the first character after the returned substring.
Returns
A newly allocated string containing the text after offset bounded by the specified boundary_type.

◆ get_text_after_offset_vfunc()

virtual Glib::ustring Atk::Text::get_text_after_offset_vfunc ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const
protectedvirtual
Deprecated:
This virtual function is deprecated and it should not be overridden.

◆ get_text_at_offset()

Glib::ustring Atk::Text::get_text_at_offset ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const

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_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_LINE_START the returned string is from the line start at or before the offset to the line start after the offset.

Deprecated: This method is deprecated since ATK version 2.9.4. Please use get_string_at_offset() instead.

Deprecated:
Use get_string_at_offset() instead.
Parameters
offsetPosition.
boundary_typeAn Atk::TextBoundary.
start_offsetThe start offset of the returned string.
end_offsetThe offset of the first character after the returned substring.
Returns
A newly allocated string containing the text at offset bounded by the specified boundary_type.

◆ get_text_at_offset_vfunc()

virtual Glib::ustring Atk::Text::get_text_at_offset_vfunc ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const
protectedvirtual

◆ get_text_before_offset()

Glib::ustring Atk::Text::get_text_before_offset ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const

Gets the specified text.

Deprecated: 2.9.3: Please use get_string_at_offset() instead.

Deprecated:
Use get_string_at_offset() instead.
Parameters
offsetPosition.
boundary_typeAn Atk::TextBoundary.
start_offsetThe start offset of the returned string.
end_offsetThe offset of the first character after the returned substring.
Returns
A newly allocated string containing the text before offset bounded by the specified boundary_type.

◆ get_text_before_offset_vfunc()

virtual Glib::ustring Atk::Text::get_text_before_offset_vfunc ( int  offset,
TextBoundary  boundary_type,
int &  start_offset,
int &  end_offset 
) const
protectedvirtual
Deprecated:
This virtual function is deprecated and it should not be overridden.

◆ get_text_vfunc()

virtual Glib::ustring Atk::Text::get_text_vfunc ( int  start_offset,
int  end_offset 
) const
protectedvirtual

◆ get_type()

static GType Atk::Text::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

◆ gobj() [1/2]

AtkText * Atk::Text::gobj ( )
inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const AtkText * Atk::Text::gobj ( ) const
inline

Provides access to the underlying C GObject.

◆ on_text_attributes_changed()

virtual void Atk::Text::on_text_attributes_changed ( )
protectedvirtual

This is a default handler for the signal signal_text_attributes_changed().

◆ on_text_caret_moved()

virtual void Atk::Text::on_text_caret_moved ( int  location)
protectedvirtual

This is a default handler for the signal signal_text_caret_moved().

◆ on_text_changed()

virtual void Atk::Text::on_text_changed ( int  position,
int  length 
)
protectedvirtual

This is a default handler for the signal signal_text_changed().

◆ on_text_selection_changed()

virtual void Atk::Text::on_text_selection_changed ( )
protectedvirtual

This is a default handler for the signal signal_text_selection_changed().

◆ operator=()

Text & Atk::Text::operator= ( Text &&  src)
noexcept

◆ remove_selection()

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

Removes the specified selection.

Parameters
selection_numThe 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.

◆ remove_selection_vfunc()

virtual bool Atk::Text::remove_selection_vfunc ( int  selection_num)
protectedvirtual

◆ set_caret_offset()

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

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

Parameters
offsetPosition.
Returns
true if success, false otherwise.

◆ set_caret_offset_vfunc()

virtual bool Atk::Text::set_caret_offset_vfunc ( int  offset)
protectedvirtual

◆ set_selection()

bool 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_numThe 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_offsetThe new start position of the selection.
end_offsetThe new end position of (e.g. offset immediately past) the selection.
Returns
true if success, false otherwise.

◆ set_selection_vfunc()

virtual bool Atk::Text::set_selection_vfunc ( int  selection_num,
int  start_offset,
int  end_offset 
)
protectedvirtual

◆ signal_text_attributes_changed()

Glib::SignalProxy< void > Atk::Text::signal_text_attributes_changed ( )
Slot Prototype:
void on_my_text_attributes_changed()

Flags: Run Last

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

◆ signal_text_caret_moved()

Glib::SignalProxy< void, int > Atk::Text::signal_text_caret_moved ( )
Slot Prototype:
void on_my_text_caret_moved(int location)

Flags: Run Last

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

Parameters
locationThe new position of the text caret.

◆ signal_text_changed()

Glib::SignalProxy< void, int, int > Atk::Text::signal_text_changed ( )
Slot Prototype:
void on_my_text_changed(int position, int length)

Flags: Run Last

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.

Deprecated: 2.9.4: Use Atk::Object::signal_text_insert() or Atk::Object::signal_text_remove() instead.

Parameters
positionThe position (character offset) of the insertion or deletion.
lengthThe length (in characters) of text inserted or deleted.

◆ signal_text_selection_changed()

Glib::SignalProxy< void > Atk::Text::signal_text_selection_changed ( )
Slot Prototype:
void on_my_text_selection_changed()

Flags: Run Last

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

Friends And Related Function Documentation

◆ wrap()

Glib::RefPtr< Atk::Text > wrap ( AtkText *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.