atkmm: Atk::Text Class Reference

atkmm 2.36.0

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

#include <atkmm/text.h>

Inheritance diagram for Atk::Text:

[legend]

Public Types
enum	ClipType { ClipType::NONE, ClipType::MIN, ClipType::MAX, ClipType::BOTH }
	Describes the type of clipping required. More...

enum	Granularity { Granularity::CHAR, Granularity::WORD, Granularity::SENTENCE, Granularity::LINE, Granularity::PARAGRAPH }
	Text granularity types used for specifying the granularity of the region of text we are interested in. More...

typedef AtkTextRectangle	Rectangle

Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify	func_destroy_notify

Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify	func_destroy_notify

Public Member Functions
	Text (Text&& src) noexcept

Text&	operator= (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_string_at_offset (int offset, Granularity 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 of the position of the caret (cursor). More...

void	get_character_extents (int offset, int& x, int& y, int& width, int& height, CoordType coords) const
	If the extent can not be obtained (e.g. missing support), all of x, y, width, height are set to -1. More...

std::vector< Attribute >	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...

std::vector< Attribute >	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, ClipType x_clip_type, ClipType y_clip_type)
	Get the ranges of text in the specified bounding box. More...

Glib::SignalProxyDetailed< void(int, int)>	signal_text_changed (const Glib::ustring& insert_or_delete={})

Glib::SignalProxyDetailed< void(int, int, const Glib::ustring&)>	signal_text_insert (const Glib::ustring& system={})

Glib::SignalProxyDetailed< void(int, int, const Glib::ustring&)>	signal_text_remove (const Glib::ustring& system={})

Glib::SignalProxy< void(int)>	signal_text_caret_moved ()

Glib::SignalProxy< void()>	signal_text_selection_changed ()

Glib::SignalProxy< void()>	signal_text_attributes_changed ()

Public Member Functions inherited from Glib::Interface
	Interface ()

	Interface (Interface &&src) noexcept

Interface &	operator= (Interface &&src) noexcept

	Interface (const Glib::Interface_Class &interface_class)

	Interface (GObject *castitem)

	~Interface () noexcept override

	Interface (const Interface &)=delete

Interface &	operator= (const Interface &)=delete

GObject *	gobj ()

const GObject *	gobj () const

Public Member Functions inherited from Glib::ObjectBase
	ObjectBase (const ObjectBase &)=delete

ObjectBase &	operator= (const ObjectBase &)=delete

void	set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)

void	get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const

void	set_property (const Glib::ustring &property_name, const PropertyType &value)

void	get_property (const Glib::ustring &property_name, PropertyType &value) const

PropertyType	get_property (const Glib::ustring &property_name) const

sigc::connection	connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)

sigc::connection	connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)

void	freeze_notify ()

void	thaw_notify ()

virtual void	reference () const

virtual void	unreference () const

GObject *	gobj ()

const GObject *	gobj () const

GObject *	gobj_copy () const

Public Member Functions inherited from sigc::trackable
	trackable () noexcept

	trackable (const trackable &src) noexcept

	trackable (trackable &&src) noexcept

	~trackable ()

void	add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const

void	notify_callbacks ()

trackable &	operator= (const trackable &src)

trackable &	operator= (trackable &&src) noexcept

void	remove_destroy_notify_callback (notifiable *data) const

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

Protected Member Functions inherited from Glib::ObjectBase
	ObjectBase ()

	ObjectBase (const char *custom_type_name)

	ObjectBase (const std::type_info &custom_type_info)

	ObjectBase (ObjectBase &&src) noexcept

ObjectBase &	operator= (ObjectBase &&src) noexcept

virtual	~ObjectBase () noexcept=0

void	initialize (GObject *castitem)

void	initialize_move (GObject castitem, Glib::ObjectBase previous_wrapper)

Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Atk::Text >	wrap (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

typedef AtkTextRectangle Atk::Text::Rectangle

Constructor & Destructor Documentation

Atk::Text::Text ( )

protected

You should derive from this class to use it.

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

noexcept

Atk::Text::~Text ( )

overridenoexcept

Member Function Documentation

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

static

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

Adds a selection bounded by the specified offsets.

Parameters

start_offset	The starting character offset of the selected region.
end_offset	The offset of the first character after the selected region.

Returns: true if successful, false otherwise.

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

protectedvirtual

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

Get the ranges of text in the specified bounding box.

Since atkmm 1.3:

Parameters

rect	An AtkTextRectangle giving the dimensions of the bounding box.
coord_type	Specify whether coordinates are relative to the screen or widget window.
x_clip_type	Specify the horizontal clip type.
y_clip_type	Specify the vertical clip type.

Returns: Array of AtkTextRange. The last element of the array returned by this function will be nullptr.

int Atk::Text::get_caret_offset ( ) const

Gets the offset of the position of the caret (cursor).

Returns: The character offset of the position of the caret or -1 if the caret is not located inside the element or in the case of any other failure.

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

protectedvirtual

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

Gets the specified text.

Parameters

offset A character offset within text.

Returns: The character at offset or 0 in the case of failure.

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

protectedvirtual

int Atk::Text::get_character_count ( ) const

Gets the character count.

Returns: The number of characters or -1 in case of failure.

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

protectedvirtual

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

If the extent can not be obtained (e.g. missing support), all of x, y, width, height are set to -1.

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

Parameters

offset	The offset of the text character for which bounding information is required.
x	Pointer for the x coordinate of the bounding box.
y	Pointer for the y coordinate 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.

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

protectedvirtual

std::vector<Attribute> 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.

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

protectedvirtual

int Atk::Text::get_n_selections ( ) const

Gets the number of selected regions.

Returns: The number of selected regions, or -1 in the case of failure.

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

protectedvirtual

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

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 of -1 in case of failure.

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

protectedvirtual

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.

If the extents can not be obtained (e.g. or missing support), the rectangle fields are set to -1.

Since atkmm 1.3:

Parameters

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.
rect	A pointer to a AtkTextRectangle which is filled in by this function.

std::vector<Attribute> 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

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 Atk::AttributeSet which contains the attributes explicitly set at offset.

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

protectedvirtual

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_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 starting character offset of the selected region.
end_offset	Passes back the ending character offset (offset immediately past) of the selected region.

Returns: A newly allocated string containing the selected text.

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

protectedvirtual

Glib::ustring Atk::Text::get_string_at_offset	(	int	offset,
		Granularity	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

offset	Position.
granularity	An Atk::TextGranularity.
start_offset	The starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented).
end_offset	The offset of the first character after the returned string, or -1 in the case of error (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.

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

Gets the specified text.

Parameters

start_offset	A starting character offset within text.
end_offset	An ending character offset within text, 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.

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

protectedvirtual

static GType Atk::Text::get_type ( )

static

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

AtkText* Atk::Text::gobj ( )

inline

Provides access to the underlying C GObject.

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

inline

Provides access to the underlying C GObject.

virtual void Atk::Text::on_text_attributes_changed ( )

protectedvirtual

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

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

protectedvirtual

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

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

protectedvirtual

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

virtual void Atk::Text::on_text_selection_changed ( )

protectedvirtual

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

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

noexcept

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

Removes the specified selection.

Parameters

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 successful, false otherwise.

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

protectedvirtual

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

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

In the case of rich-text content, this method should either grab focus or move the sequential focus navigation starting point (if the application supports this concept) as if the user had clicked on the new caret position. Typically, this means that the target of this operation is the node containing the new caret position or one of its ancestors. In other words, after this method is called, if the user advances focus, it should move to the first focusable node following the new caret position.

Calling this method should also scroll the application viewport in a way that matches the behavior of the application's typical caret motion or tab navigation as closely as possible. This also means that if the application's caret motion or focus navigation does not trigger a scroll operation, this method should not trigger one either. If the application does not have a caret motion or focus navigation operation, this method should try to scroll the new caret position into view while minimizing unnecessary scroll motion.

Parameters

offset The character offset of the new caret position.

Returns: true if successful, false otherwise.

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

protectedvirtual

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_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 starting character offset of the selection.
end_offset	The new end position of (e.g. offset immediately past) the selection.

Returns: true if successful, false otherwise.

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

protectedvirtual

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.

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

location The new position of the text caret.

Glib::SignalProxyDetailed<void(int, int)> Atk::Text::signal_text_changed ( const Glib::ustring & insert_or_delete = {} )

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

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

Glib::SignalProxyDetailed<void(int, int, const Glib::ustring&)> Atk::Text::signal_text_insert ( const Glib::ustring & system = {} )

Slot Prototype:: void on_my_text_insert(int position, int length, const Glib::ustring& text)

Flags: Run Last

The "text-insert" signal is emitted when a new text is inserted. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included.

Parameters

position	The position (character offset) of the insertion.
length	The length (in characters) of text inserted.
text	The new text inserted.

Glib::SignalProxyDetailed<void(int, int, const Glib::ustring&)> Atk::Text::signal_text_remove ( const Glib::ustring & system = {} )

Slot Prototype:: void on_my_text_remove(int position, int length, const Glib::ustring& text)

Flags: Run Last

The "text-remove" signal is emitted when a new text is removed. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included.

Parameters

position	The position (character offset) of the removal.
length	The length (in characters) of text removed.
text	The old text removed.

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

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

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

Parameters

object	The C instance.
take_copy	False 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.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation