Top |
void | text-attributes-changed | Run Last |
void | text-caret-moved | Run Last |
void | text-changed | Has Details |
void | text-insert | Has Details |
void | text-remove | Has Details |
void | text-selection-changed | Run Last |
AtkText | |
struct | AtkTextIface |
enum | AtkTextBoundary |
enum | AtkTextGranularity |
enum | AtkTextClipType |
struct | AtkTextRange |
struct | AtkTextRectangle |
enum | AtkTextAttribute |
GBoxed ╰── AtkTextRange GEnum ├── AtkTextAttribute ├── AtkTextBoundary ├── AtkTextClipType ╰── AtkTextGranularity GInterface ╰── AtkText
AtkText should be implemented by AtkObjects on behalf of widgets that have text content which is either attributed or otherwise non-trivial. AtkObjects whose text content is simple, unattributed, and very brief may expose that content via atk_object_get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the AtkText interface should be used to expose the text content. In the case of editable text content, AtkEditableText (a subtype of the AtkText interface) should be implemented instead.
AtkText 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.
gchar * atk_text_get_text (AtkText *text
,gint start_offset
,gint end_offset
);
Gets the specified text.
text |
an AtkText |
|
start_offset |
a starting character offset within |
|
end_offset |
an ending character offset within |
a newly allocated string containing the text from start_offset
up
to, but not including end_offset
. Use g_free()
to free the returned
string.
gunichar atk_text_get_character_at_offset (AtkText *text
,gint offset
);
Gets the specified text.
gchar * atk_text_get_text_after_offset (AtkText *text
,gint offset
,AtkTextBoundary boundary_type
,gint *start_offset
,gint *end_offset
);
atk_text_get_text_after_offset
has been deprecated since version 2.9.3 and should not be used in newly-written code.
Please use atk_text_get_string_at_offset()
instead.
Gets the specified text.
text |
an AtkText |
|
offset |
position |
|
boundary_type |
||
start_offset |
the starting character offset of the returned string. |
[out] |
end_offset |
the offset of the first character after the returned substring. |
[out] |
a newly allocated string containing the text after offset
bounded
by the specified boundary_type
. Use g_free()
to free the returned
string.
gchar * atk_text_get_text_at_offset (AtkText *text
,gint offset
,AtkTextBoundary boundary_type
,gint *start_offset
,gint *end_offset
);
atk_text_get_text_at_offset
is deprecated and should not be used in newly-written code.
This method is deprecated since ATK version
2.9.4. Please use atk_text_get_string_at_offset()
instead.
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.
text |
an AtkText |
|
offset |
position |
|
boundary_type |
||
start_offset |
the starting character offset of the returned string. |
[out] |
end_offset |
the offset of the first character after the returned substring. |
[out] |
a newly allocated string containing the text at offset
bounded
by the specified boundary_type
. Use g_free()
to free the returned
string.
gchar * atk_text_get_text_before_offset (AtkText *text
,gint offset
,AtkTextBoundary boundary_type
,gint *start_offset
,gint *end_offset
);
atk_text_get_text_before_offset
has been deprecated since version 2.9.3 and should not be used in newly-written code.
Please use atk_text_get_string_at_offset()
instead.
Gets the specified text.
text |
an AtkText |
|
offset |
position |
|
boundary_type |
||
start_offset |
the starting character offset of the returned string. |
[out] |
end_offset |
the offset of the first character after the returned substring. |
[out] |
a newly allocated string containing the text before offset
bounded
by the specified boundary_type
. Use g_free()
to free the returned
string.
gchar * atk_text_get_string_at_offset (AtkText *text
,gint offset
,AtkTextGranularity granularity
,gint *start_offset
,gint *end_offset
);
Gets a portion of the text exposed through an AtkText 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.
text |
an AtkText |
|
offset |
position |
|
granularity |
||
start_offset |
the starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented). |
[out] |
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). |
[out] |
a newly allocated string containing the text at
the offset
bounded by the specified granularity
. Use g_free()
to free the returned string. Returns NULL
if the offset is invalid
or no implementation is available.
[nullable]
Since: 2.10
gint
atk_text_get_caret_offset (AtkText *text
);
Gets the offset of the position of the caret (cursor).
void atk_text_get_character_extents (AtkText *text
,gint offset
,gint *x
,gint *y
,gint *width
,gint *height
,AtkCoordType coords
);
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.
text |
an AtkText |
|
offset |
The offset of the text character for which bounding information is required. |
|
x |
Pointer for the x coordinate of the bounding box. |
[out][optional] |
y |
Pointer for the y coordinate of the bounding box. |
[out][optional] |
width |
Pointer for the width of the bounding box. |
[out][optional] |
height |
Pointer for the height of the bounding box. |
[out][optional] |
coords |
specify whether coordinates are relative to the screen or widget window |
AtkAttributeSet * atk_text_get_run_attributes (AtkText *text
,gint offset
,gint *start_offset
,gint *end_offset
);
Creates an AtkAttributeSet 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. Note that end_offset
is the offset of the first character
after the range. See the enum AtkTextAttribute for types of text
attributes that can be returned. Note that other attributes may also be
returned.
text |
an AtkText |
|
offset |
the character offset at which to get the attributes, -1 means the offset of the character to be inserted at the caret location. |
|
start_offset |
the address to put the start offset of the range. |
[out] |
end_offset |
the address to put the end offset of the range. |
[out] |
an AtkAttributeSet which contains the attributes
explicitly set at offset
. This AtkAttributeSet should be freed by
a call to atk_attribute_set_free()
.
[transfer full]
AtkAttributeSet *
atk_text_get_default_attributes (AtkText *text
);
Creates an AtkAttributeSet 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.
an AtkAttributeSet which contains the default text
attributes for this AtkText. This AtkAttributeSet should be freed by
a call to atk_attribute_set_free()
.
[transfer full]
gint
atk_text_get_character_count (AtkText *text
);
Gets the character count.
gint atk_text_get_offset_at_point (AtkText *text
,gint x
,gint y
,AtkCoordType coords
);
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
.
text |
an AtkText |
|
x |
screen x-position of character |
|
y |
screen y-position of character |
|
coords |
specify whether coordinates are relative to the screen or widget window |
AtkTextRange ** atk_text_get_bounded_ranges (AtkText *text
,AtkTextRectangle *rect
,AtkCoordType coord_type
,AtkTextClipType x_clip_type
,AtkTextClipType y_clip_type
);
Get the ranges of text in the specified bounding box.
[virtual get_bounded_ranges]
text |
an AtkText |
|
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. |
Array of AtkTextRange. The last element of the array returned by this function will be NULL.
[array zero-terminated=1]
Since: 1.3
void atk_text_get_range_extents (AtkText *text
,gint start_offset
,gint end_offset
,AtkCoordType coord_type
,AtkTextRectangle *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.
text |
an AtkText |
|
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. |
[out] |
Since: 1.3
void
atk_text_free_ranges (AtkTextRange **ranges
);
Frees the memory associated with an array of AtkTextRange. It is assumed that the array was returned by the function atk_text_get_bounded_ranges and is NULL terminated.
Since: 1.3
gint
atk_text_get_n_selections (AtkText *text
);
Gets the number of selected regions.
gchar * atk_text_get_selection (AtkText *text
,gint selection_num
,gint *start_offset
,gint *end_offset
);
Gets the text from the specified selection.
text |
an AtkText |
|
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. |
[out] |
end_offset |
passes back the ending character offset (offset immediately past) of the selected region. |
[out] |
a newly allocated string containing the selected text. Use g_free()
to free the returned string.
gboolean atk_text_add_selection (AtkText *text
,gint start_offset
,gint end_offset
);
Adds a selection bounded by the specified offsets.
text |
an AtkText |
|
start_offset |
the starting character offset of the selected region |
|
end_offset |
the offset of the first character after the selected region. |
gboolean atk_text_remove_selection (AtkText *text
,gint selection_num
);
Removes the specified selection.
text |
an AtkText |
|
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. |
gboolean atk_text_set_selection (AtkText *text
,gint selection_num
,gint start_offset
,gint end_offset
);
Changes the start and end offset of the specified selection.
text |
an AtkText |
|
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 |
gboolean atk_text_set_caret_offset (AtkText *text
,gint 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.
void
atk_attribute_set_free (AtkAttributeSet *attrib_set
);
Frees the memory used by an AtkAttributeSet, including all its AtkAttributes.
AtkTextAttribute
atk_text_attribute_register (const gchar *name
);
Associate name
with a new AtkTextAttribute
const gchar *
atk_text_attribute_get_name (AtkTextAttribute attr
);
Gets the name corresponding to the AtkTextAttribute
AtkTextAttribute
atk_text_attribute_for_name (const gchar *name
);
Get the AtkTextAttribute type corresponding to a text attribute name.
the AtkTextAttribute enumerated type corresponding to the specified name, or ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found.
const gchar * atk_text_attribute_get_value (AtkTextAttribute attr
,gint index_
);
Gets the value for the index of the AtkTextAttribute
attr |
The AtkTextAttribute for which a value is required |
|
index_ |
The index of the required value |
a string containing the value; this string
should not be freed; NULL
is returned if there are no values
maintained for the attr value.
[nullable]
gboolean atk_text_scroll_substring_to (AtkText *text
,gint start_offset
,gint end_offset
,AtkScrollType type
);
Makes a substring of text
visible on the screen by scrolling all necessary parents.
text |
an AtkText |
|
start_offset |
start offset in the |
|
end_offset |
end offset in the |
|
type |
specify where the object should be made visible. |
Since: 2.32
gboolean atk_text_scroll_substring_to_point (AtkText *text
,gint start_offset
,gint end_offset
,AtkCoordType coords
,gint x
,gint y
);
Move the top-left of a substring of text
to a given position of the screen
by scrolling all necessary parents.
text |
an AtkText |
|
start_offset |
start offset in the |
|
end_offset |
end offset in the |
|
coords |
specify whether coordinates are relative to the screen or to the parent object. |
|
x |
x-position where to scroll to |
|
y |
y-position where to scroll to |
Since: 2.32
struct AtkTextIface { GTypeInterface parent; gchar* (* get_text) (AtkText *text, gint start_offset, gint end_offset); gchar* (* get_text_after_offset) (AtkText *text, gint offset, AtkTextBoundary boundary_type, gint *start_offset, gint *end_offset); gchar* (* get_text_at_offset) (AtkText *text, gint offset, AtkTextBoundary boundary_type, gint *start_offset, gint *end_offset); gunichar (* get_character_at_offset) (AtkText *text, gint offset); gchar* (* get_text_before_offset) (AtkText *text, gint offset, AtkTextBoundary boundary_type, gint *start_offset, gint *end_offset); gint (* get_caret_offset) (AtkText *text); AtkAttributeSet* (* get_run_attributes) (AtkText *text, gint offset, gint *start_offset, gint *end_offset); AtkAttributeSet* (* get_default_attributes) (AtkText *text); void (* get_character_extents) (AtkText *text, gint offset, gint *x, gint *y, gint *width, gint *height, AtkCoordType coords); gint (* get_character_count) (AtkText *text); gint (* get_offset_at_point) (AtkText *text, gint x, gint y, AtkCoordType coords); gint (* get_n_selections) (AtkText *text); gchar* (* get_selection) (AtkText *text, gint selection_num, gint *start_offset, gint *end_offset); gboolean (* add_selection) (AtkText *text, gint start_offset, gint end_offset); gboolean (* remove_selection) (AtkText *text, gint selection_num); gboolean (* set_selection) (AtkText *text, gint selection_num, gint start_offset, gint end_offset); gboolean (* set_caret_offset) (AtkText *text, gint offset); /* * signal handlers */ void (* text_changed) (AtkText *text, gint position, gint length); void (* text_caret_moved) (AtkText *text, gint location); void (* text_selection_changed) (AtkText *text); void (* text_attributes_changed) (AtkText *text); void (* get_range_extents) (AtkText *text, gint start_offset, gint end_offset, AtkCoordType coord_type, AtkTextRectangle *rect); AtkTextRange** (* get_bounded_ranges) (AtkText *text, AtkTextRectangle *rect, AtkCoordType coord_type, AtkTextClipType x_clip_type, AtkTextClipType y_clip_type); gchar* (* get_string_at_offset) (AtkText *text, gint offset, AtkTextGranularity granularity, gint *start_offset, gint *end_offset); /* * Scrolls this text range so it becomes visible on the screen. * * scroll_substring_to lets the implementation compute an appropriate target * position on the screen, with type used as a positioning hint. * * scroll_substring_to_point lets the client specify a precise target position * on the screen for the top-left of the substring. * * Since ATK 2.32 */ gboolean (* scroll_substring_to) (AtkText *text, gint start_offset, gint end_offset, AtkScrollType type); gboolean (* scroll_substring_to_point) (AtkText *text, gint start_offset, gint end_offset, AtkCoordType coords, gint x, gint y); };
GTypeInterface |
||
Gets specified text. This virtual function is deprecated and it should not be overridden. |
||
Gets specified text. This virtual function is deprecated and it should not be overridden. |
||
Gets specified text. This virtual function is deprecated and it should not be overridden. |
||
the signal handler which is executed when there is a text change. This virtual function is deprecated sice 2.9.4 and it should not be overriden. |
||
Gets a portion of the text exposed through an AtkText 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. |
||
Text boundary types used for specifying boundaries for regions of text. This enumeration is deprecated since 2.9.4 and should not be used. Use AtkTextGranularity with atk_text_get_string_at_offset instead.
Boundary is the boundary between characters (including non-printing characters) |
||
Boundary is the start (i.e. first character) of a word. |
||
Boundary is the end (i.e. last character) of a word. |
||
Boundary is the first character in a sentence. |
||
Boundary is the last (terminal) character in a sentence; in languages which use "sentence stop" punctuation such as English, the boundary is thus the '.', '?', or similar terminal punctuation character. |
||
Boundary is the initial character of the content or a character immediately following a newline, linefeed, or return character. |
||
Boundary is the linefeed, or return character. |
Text granularity types used for specifying the granularity of the region of text we are interested in.
Granularity is defined by the boundaries between characters (including non-printing characters) |
||
Granularity is defined by the boundaries of a word, starting at the beginning of the current word and finishing at the beginning of the following one, if present. |
||
Granularity is defined by the boundaries of a sentence, starting at the beginning of the current sentence and finishing at the beginning of the following one, if present. |
||
Granularity is defined by the boundaries of a line, starting at the beginning of the current line and finishing at the beginning of the following one, if present. |
||
Granularity is defined by the boundaries of a paragraph, starting at the beginning of the current paragraph and finishing at the beginning of the following one, if present. |
struct AtkTextRange { AtkTextRectangle bounds; gint start_offset; gint end_offset; gchar* content; };
A structure used to describe a text range.
AtkTextRectangle |
A rectangle giving the bounds of the text range |
|
gint |
The start offset of a AtkTextRange |
|
gint |
The end offset of a AtkTextRange |
|
gchar * |
The text in the text range |
struct AtkTextRectangle { gint x; gint y; gint width; gint height; };
A structure used to store a rectangle used by AtkText.
Describes the text attributes supported
Invalid attribute, like bad spelling or grammar. |
||
The pixel width of the left margin |
||
The pixel width of the right margin |
||
The number of pixels that the text is indented |
||
Either "true" or "false" indicating whether text is visible or not |
||
Either "true" or "false" indicating whether text is editable or not |
||
Pixels of blank space to leave above each newline-terminated line. |
||
Pixels of blank space to leave below each newline-terminated line. |
||
Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph). |
||
"true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character. |
||
Number of pixels that the characters are risen above the baseline. See also ATK_TEXT_ATTR_TEXT_POSITION. |
||
"none", "single", "double", "low", or "error" |
||
"true" or "false" whether the text is strikethrough |
||
The size of the characters in points. eg: 10 |
||
The scale of the characters. The value is a string representation of a double |
||
The weight of the characters. |
||
The language used |
||
The font family name |
||
The background color. The value is an RGB value of the format " |
||
The foreground color. The value is an RGB value of the format " |
||
"true" if a GdkBitmap is set for stippling the background color. |
||
"true" if a GdkBitmap is set for stippling the foreground color. |
||
The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char". |
||
The direction of the text, if set. Values are "none", "ltr" or "rtl" |
||
The justification of the text, if set. Values are "left", "right", "center" or "fill" |
||
The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded" |
||
The capitalization variant of the text, if set. Values are "normal" or "small_caps" |
||
The slant style of the text, if set. Values are "normal", "oblique" or "italic" |
||
The vertical position with respect to the baseline. Values are "baseline", "super", or "sub". Note that a super or sub text attribute refers to position with respect to the baseline of the prior character. |
||
not a valid text attribute, used for finding end of enumeration |
“text-attributes-changed”
signalvoid user_function (AtkText *atktext, gpointer user_data)
The "text-attributes-changed" signal is emitted when the text attributes of the text of an object which implements AtkText changes.
atktext |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“text-caret-moved”
signalvoid user_function (AtkText *atktext, int arg1, gpointer user_data)
The "text-caret-moved" signal is emitted when the caret position of the text of an object which implements AtkText changes.
atktext |
the object which received the signal. |
|
arg1 |
The new position of the text caret. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“text-changed”
signalvoid user_function (AtkText *atktext, int arg1, int arg2, gpointer user_data)
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.
AtkText::text-changed
has been deprecated since version 2.9.4 and should not be used in newly-written code.
Use “text-insert” or “text-remove” instead.
atktext |
the object which received the signal. |
|
arg1 |
The position (character offset) of the insertion or deletion. |
|
arg2 |
The length (in characters) of text inserted or deleted. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details
“text-insert”
signalvoid user_function (AtkText *atktext, int arg1, int arg2, char *arg3, gpointer user_data)
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.
atktext |
the object which received the signal. |
|
arg1 |
The position (character offset) of the insertion. |
|
arg2 |
The length (in characters) of text inserted. |
|
arg3 |
The new text inserted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details
“text-remove”
signalvoid user_function (AtkText *atktext, int arg1, int arg2, char *arg3, gpointer user_data)
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.
atktext |
the object which received the signal. |
|
arg1 |
The position (character offset) of the removal. |
|
arg2 |
The length (in characters) of text removed. |
|
arg3 |
The old text removed |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details
“text-selection-changed”
signalvoid user_function (AtkText *atktext, gpointer user_data)
The "text-selection-changed" signal is emitted when the selected text of an object which implements AtkText changes.
atktext |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last