Atk::Text Class Reference

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

Collaboration diagram for Atk::Text:

Public Types
typedef AtkTextRectangle	Rectangle
Public Member Functions
virtual	~Text ()
AtkText*	gobj ()
	Provides access to the underlying C GObject.
const AtkText*	gobj () const
	Provides access to the underlying C GObject.
Glib::ustring	get_text (int start_offset, int end_offset) const
	Gets the specified text.
gunichar	get_character_at_offset (int offset) const
	Gets the specified text.
Glib::ustring	get_text_after_offset (int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const
	Gets the specified text.
Glib::ustring	get_text_at_offset (int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const
	Gets the specified text.
Glib::ustring	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
	Gets the offset position of the caret (cursor).
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.
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.
AttributeSet	get_default_attributes () const
	Creates an Atk::AttributeSet which consists of the default values of attributes for the text.
int	get_character_count () const
	Gets the character count.
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.
Glib::ustring	get_selection (int selection_num, int& start_offset, int& end_offset) const
	Gets the text from the specified selection.
bool	add_selection (int start_offset, int end_offset)
	Adds a 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.
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.
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.
Glib::SignalProxy2< void, int, int >	signal_text_changed ()
Glib::SignalProxy1< void, int >	signal_text_caret_moved ()
Glib::SignalProxy0< void >	signal_text_selection_changed ()
Glib::SignalProxy0< void >	signal_text_attributes_changed ()
Static Public Member Functions
static void	add_interface (GType gtype_implementer)
Protected Member Functions
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)
virtual void	on_text_caret_moved (int location)
virtual void	on_text_selection_changed ()
virtual void	on_text_attributes_changed ()
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.

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

virtual Atk::Text::~Text ( ) [virtual]

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 start position of the selected region.
	end_offset	The offset of the first character after the selected region.

Returns:: true if success, false otherwise.

virtual bool Atk::Text::add_selection_vfunc	(	int	start_offset,
		int	end_offset
	)			`[protected, virtual]`

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 gtkmm 1.3:

Parameters:

	rect	An AtkTextRectagle 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 0.

int Atk::Text::get_caret_offset ( ) const

Gets the offset position of the caret (cursor).

Returns:: The offset position of the caret (cursor).

virtual int Atk::Text::get_caret_offset_vfunc ( ) const [protected, virtual]

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

Gets the specified text.

Parameters:

offset

Position.

Returns:: The character at offset.

virtual gunichar Atk::Text::get_character_at_offset_vfunc ( int offset ) const [protected, virtual]

int Atk::Text::get_character_count ( ) const

Gets the character count.

Returns:: The number of characters.

virtual int Atk::Text::get_character_count_vfunc ( ) const [protected, virtual]

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:

	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.

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

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.

virtual AtkAttributeSet* Atk::Text::get_default_attributes_vfunc ( ) const [protected, virtual]

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.

virtual int Atk::Text::get_n_selections_vfunc ( ) const [protected, virtual]

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.

virtual int Atk::Text::get_offset_at_point_vfunc	(	int	x,
		int	y,
		CoordType	coords
	)			const `[protected, virtual]`

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

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:

	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 `[protected, virtual]`

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 start position of the selected region.
	end_offset	Passes back the end position of (e.g. offset immediately past) the selected region.

Returns:: The selected text.

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

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

Gets the specified text.

Parameters:

	start_offset	Start position.
	end_offset	End position.

Returns:: The text from start_offset up to, but not including end_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.

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.

Parameters:

	offset	Position.
	boundary_type	An Atk::TextBoundary.
	start_offset	The start offset of the returned string.
	end_offset	The offset of the first character after the returned substring.

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

virtual Glib::ustring Atk::Text::get_text_after_offset_vfunc	(	int	offset,
		TextBoundary	boundary_type,
		int &	start_offset,
		int &	end_offset
	)			const `[protected, virtual]`

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

Parameters:

	offset	Position.
	boundary_type	An Atk::TextBoundary.
	start_offset	The start offset of the returned string.
	end_offset	The offset of the first character after the returned substring.

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

virtual Glib::ustring Atk::Text::get_text_at_offset_vfunc	(	int	offset,
		TextBoundary	boundary_type,
		int &	start_offset,
		int &	end_offset
	)			const `[protected, virtual]`

Glib::ustring Atk::Text::get_text_before_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 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.

Parameters:

	offset	Position.
	boundary_type	An Atk::TextBoundary.
	start_offset	The start offset of the returned string.
	end_offset	The offset of the first character after the returned substring.

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

virtual Glib::ustring Atk::Text::get_text_before_offset_vfunc	(	int	offset,
		TextBoundary	boundary_type,
		int &	start_offset,
		int &	end_offset
	)			const `[protected, virtual]`

virtual Glib::ustring Atk::Text::get_text_vfunc	(	int	start_offset,
		int	end_offset
	)			const `[protected, virtual]`

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

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Atk::NoOpObject.

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

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Atk::NoOpObject.

virtual void Atk::Text::on_text_attributes_changed ( ) [protected, virtual]

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

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

virtual void Atk::Text::on_text_selection_changed ( ) [protected, virtual]

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

virtual bool Atk::Text::remove_selection_vfunc ( int selection_num ) [protected, virtual]

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

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

Parameters:

offset

Position.

Returns:: true if success, false otherwise.

virtual bool Atk::Text::set_caret_offset_vfunc ( int offset ) [protected, virtual]

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

virtual bool Atk::Text::set_selection_vfunc	(	int	selection_num,
		int	start_offset,
		int	end_offset
	)			`[protected, virtual]`

Glib::SignalProxy0< void > Atk::Text::signal_text_attributes_changed ( )

Prototype:: void on_my_text_attributes_changed()

Glib::SignalProxy1< void,int > Atk::Text::signal_text_caret_moved ( )

Prototype:: void on_my_text_caret_moved(int location)

Glib::SignalProxy2< void,int,int > Atk::Text::signal_text_changed ( )

Prototype:: void on_my_text_changed(int position, int length)

Glib::SignalProxy0< void > Atk::Text::signal_text_selection_changed ( )

Prototype:: void on_my_text_selection_changed()

Friends And Related Function Documentation

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

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.

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

atkmm/text.h

Atk::Text Class Reference

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