atkmm
2.36.1
|
The ATK interface implemented by components with text content. More...
#include <atkmm/text.h>
Public Types | |
enum class | ClipType { NONE , MIN , MAX , BOTH } |
Describes the type of clipping required. More... | |
enum class | Granularity { CHAR , WORD , SENTENCE , LINE , PARAGRAPH } |
Text granularity types used for specifying the granularity of the region of text we are interested in. More... | |
typedef AtkTextRectangle | Rectangle |
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 () |
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... | |
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... | |
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.
typedef AtkTextRectangle Atk::Text::Rectangle |
|
protected |
You should derive from this class to use it.
|
noexcept |
|
overridenoexcept |
|
static |
bool Atk::Text::add_selection | ( | int | start_offset, |
int | end_offset | ||
) |
Adds a selection bounded by the specified offsets.
start_offset | The starting character offset of the selected region. |
end_offset | The offset of the first character after the selected region. |
true
if successful, false
otherwise.
|
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.
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. |
nullptr
. int Atk::Text::get_caret_offset | ( | ) | const |
Gets the offset of the position of the caret (cursor).
|
protectedvirtual |
gunichar Atk::Text::get_character_at_offset | ( | int | offset | ) | const |
Gets the specified text.
offset | A character offset within text. |
|
protectedvirtual |
int Atk::Text::get_character_count | ( | ) | const |
Gets the character count.
|
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.
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. |
|
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.
|
protectedvirtual |
int Atk::Text::get_n_selections | ( | ) | const |
Gets the number of selected regions.
|
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.
x | Screen x-position of character. |
y | Screen y-position of character. |
coords | Specify whether coordinates are relative to the screen or widget window. |
|
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.
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.
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. |
|
protectedvirtual |
Glib::ustring Atk::Text::get_selection | ( | int | selection_num, |
int & | start_offset, | ||
int & | end_offset | ||
) | const |
Gets the text from the specified selection.
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. |
|
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.
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). |
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.
start_offset | A starting character offset within text. |
end_offset | An ending character offset within text, or -1 for the end of the string. |
|
protectedvirtual |
|
static |
Get the GType for this class, for use with the underlying GObject type system.
|
inline |
Provides access to the underlying C GObject.
|
inline |
Provides access to the underlying C GObject.
|
protectedvirtual |
This is a default handler for the signal signal_text_attributes_changed().
|
protectedvirtual |
This is a default handler for the signal signal_text_caret_moved().
|
protectedvirtual |
This is a default handler for the signal signal_text_changed().
|
protectedvirtual |
This is a default handler for the signal signal_text_selection_changed().
bool Atk::Text::remove_selection | ( | int | selection_num | ) |
Removes the specified selection.
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. |
true
if successful, false
otherwise.
|
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.
offset | The character offset of the new caret position. |
true
if successful, false
otherwise.
|
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.
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. |
true
if successful, false
otherwise.
|
protectedvirtual |
Glib::SignalProxy<void()> Atk::Text::signal_text_attributes_changed | ( | ) |
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 | ( | ) |
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.
location | The new position of the text caret. |
Glib::SignalProxyDetailed<void(int, int)> Atk::Text::signal_text_changed | ( | const Glib::ustring & | insert_or_delete = {} | ) |
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.
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 = {} | ) |
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.
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 = {} | ) |
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.
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 | ( | ) |
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.
|
related |
A Glib::wrap() method for this object.
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. |