Module: Atk::Text

Defined in:
(unknown)

Overview

The ATK interface implemented by components with text content.

Atk::Text should be implemented by #AtkObjects 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, the Atk::Text interface should be used to expose the text content. In the case of editable text content, Atk::EditableText (a subtype of the #AtkText 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.

Instance Method Summary collapse

Instance Method Details

#add_selection(text, start_offset, end_offset) ⇒ Boolean

Returns true if successful, false otherwise.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • start_offset (Integer) —

    the starting character offset of the selected region

  • end_offset (Integer) —

    the offset of the first character after the selected region.

Returns:

  • (Boolean) —

    true if successful, false otherwise

#caret_offset ⇒ Integer

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

Returns:

  • (Integer) —

    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.

#caret_offset=(offset) ⇒ Boolean

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 (Integer) —

    the character offset of the new caret position

Returns:

  • (Boolean) —

    true if successful, false otherwise.

#character_count ⇒ Integer

Gets the character count.

Returns:

  • (Integer) —

    the number of characters or -1 in case of failure.

#default_attributes ⇒ Atk::AttributeSet

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:

  • (Atk::AttributeSet) —

    an Atk::AttributeSet which contains the default text attributes for this Atk::Text. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free().

#get_bounded_ranges(text, rect, coord_type, x_clip_type, y_clip_type) ⇒ Array<Atk::TextRange>

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

Parameters:

Returns:

  • (Array<Atk::TextRange>) —

    Array of AtkTextRange. The last element of the array returned by this function will be NULL.

#get_caret_offset(text) ⇒ Integer

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.

Parameters:

Returns:

  • (Integer) —

    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.

#get_character_at_offset(text, offset) ⇒ String

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

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    a character offset within text

Returns:

  • (String) —

    the character at offset or 0 in the case of failure.

#get_character_count(text) ⇒ Integer

Returns the number of characters or -1 in case of failure.

Parameters:

Returns:

  • (Integer) —

    the number of characters or -1 in case of failure.

#get_character_extents(text, offset, x, y, width, height, coords) ⇒ nil

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    The offset of the text character for which bounding information is required.

  • x (Integer) —

    Pointer for the x coordinate of the bounding box

  • y (Integer) —

    Pointer for the y coordinate of the bounding box

  • width (Integer) —

    Pointer for the width of the bounding box

  • height (Integer) —

    Pointer for the height of the bounding box

  • coords (Atk::CoordType) —

    specify whether coordinates are relative to the screen or widget window

Returns:

  • (nil)

#get_default_attributes(text) ⇒ Atk::AttributeSet

Returns an Atk::AttributeSet which contains the default text attributes for this Atk::Text. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free().

Parameters:

Returns:

  • (Atk::AttributeSet) —

    an Atk::AttributeSet which contains the default text attributes for this Atk::Text. This #AtkAttributeSet should be freed by a call to atk_attribute_set_free().

#get_n_selections(text) ⇒ Integer

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

Parameters:

Returns:

  • (Integer) —

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

#get_offset_at_point(text, x, y, coords) ⇒ Integer

widget window

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • x (Integer) —

    screen x-position of character

  • y (Integer) —

    screen y-position of character

  • coords (Atk::CoordType) —

    specify whether coordinates are relative to the screen or

Returns:

  • (Integer) —

    the offset to the character which is located at the specified x and y coordinates of -1 in case of failure.

#get_range_extents(text, start_offset, end_offset, coord_type, rect) ⇒ nil

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • start_offset (Integer) —

    The offset of the first text character for which boundary information is required.

  • end_offset (Integer) —

    The offset of the text character after the last character for which boundary information is required.

  • coord_type (Atk::CoordType) —

    Specify whether coordinates are relative to the screen or widget window.

  • rect (Atk::TextRectangle) —

    A pointer to a AtkTextRectangle which is filled in by this function.

Returns:

  • (nil)

#get_run_attributes(text, offset, start_offset, end_offset) ⇒ Atk::AttributeSet

the character to be inserted at the caret location.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    the character offset at which to get the attributes, -1 means the offset of

  • start_offset (Integer) —

    the address to put the start offset of the range

  • end_offset (Integer) —

    the address to put the end offset of the range

Returns:

  • (Atk::AttributeSet) —

    an Atk::AttributeSet which contains the attributes explicitly set at offset. This Atk::AttributeSet should be freed by a call to atk_attribute_set_free().

#get_selection(text, selection_num, start_offset, end_offset) ⇒ String

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. of the selected region

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • selection_num (Integer) —

    The selection number. The selected regions are

  • start_offset (Integer) —

    passes back the starting character offset of the selected region

  • end_offset (Integer) —

    passes back the ending character offset (offset immediately past)

Returns:

  • (String) —

    a newly allocated string containing the selected text. Use g_free() to free the returned string.

#get_string_at_offset(text, offset, granularity, start_offset, end_offset) ⇒ String

Returns a newly allocated string containing the text at the offset bounded by the specified granularity. Use g_free() to free the returned string. Returns nil if the offset is invalid or no implementation is available.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    position

  • granularity (Atk::TextGranularity) —

    An Atk::TextGranularity

  • start_offset (Integer) —

    the starting character offset of the returned string, or -1 in the case of error (e.g. invalid offset, not implemented)

  • end_offset (Integer) —

    the offset of the first character after the returned string, or -1 in the case of error (e.g. invalid offset, not implemented)

Returns:

  • (String) —

    a newly allocated string containing the text at the offset bounded by the specified granularity. Use g_free() to free the returned string. Returns nil if the offset is invalid or no implementation is available.

#get_text(text, start_offset, end_offset) ⇒ String

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

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • start_offset (Integer) —

    a starting character offset within text

  • end_offset (Integer) —

    an ending character offset within text, or -1 for the end of the string.

Returns:

  • (String) —

    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.

#get_text_after_offset(text, offset, boundary_type, start_offset, end_offset) ⇒ String

Returns a newly allocated string containing the text after offset bounded by the specified boundary_type. Use g_free() to free the returned string.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    position

  • boundary_type (Atk::TextBoundary) —

    An Atk::TextBoundary

  • start_offset (Integer) —

    the starting character offset of the returned string

  • end_offset (Integer) —

    the offset of the first character after the returned substring

Returns:

  • (String) —

    a newly allocated string containing the text after offset bounded by the specified boundary_type. Use g_free() to free the returned string.

#get_text_at_offset(text, offset, boundary_type, start_offset, end_offset) ⇒ String

Returns a newly allocated string containing the text at offset bounded by the specified boundary_type. Use g_free() to free the returned string.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    position

  • boundary_type (Atk::TextBoundary) —

    An Atk::TextBoundary

  • start_offset (Integer) —

    the starting character offset of the returned string

  • end_offset (Integer) —

    the offset of the first character after the returned substring

Returns:

  • (String) —

    a newly allocated string containing the text at offset bounded by the specified boundary_type. Use g_free() to free the returned string.

#get_text_before_offset(text, offset, boundary_type, start_offset, end_offset) ⇒ String

Returns a newly allocated string containing the text before offset bounded by the specified boundary_type. Use g_free() to free the returned string.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    position

  • boundary_type (Atk::TextBoundary) —

    An Atk::TextBoundary

  • start_offset (Integer) —

    the starting character offset of the returned string

  • end_offset (Integer) —

    the offset of the first character after the returned substring

Returns:

  • (String) —

    a newly allocated string containing the text before offset bounded by the specified boundary_type. Use g_free() to free the returned string.

#n_selections ⇒ Integer

Gets the number of selected regions.

Returns:

  • (Integer) —

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

#remove_selection(text, selection_num) ⇒ Boolean

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.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • selection_num (Integer) —

    The selection number. The selected regions are

Returns:

  • (Boolean) —

    true if successful, false otherwise

#scroll_substring_to(text, start_offset, end_offset, type) ⇒ Boolean

Returns whether scrolling was successful.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • start_offset (Integer) —

    start offset in the text

  • end_offset (Integer) —

    end offset in the text, or -1 for the end of the text.

  • type (Atk::ScrollType) —

    specify where the object should be made visible.

Returns:

  • (Boolean) —

    whether scrolling was successful.

#scroll_substring_to_point(text, start_offset, end_offset, coords, x, y) ⇒ Boolean

parent object.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • start_offset (Integer) —

    start offset in the text

  • end_offset (Integer) —

    end offset in the text, or -1 for the end of the text.

  • coords (Atk::CoordType) —

    specify whether coordinates are relative to the screen or to the

  • x (Integer) —

    x-position where to scroll to

  • y (Integer) —

    y-position where to scroll to

Returns:

  • (Boolean) —

    whether scrolling was successful.

#set_caret_offset(text, offset) ⇒ Boolean

Returns true if successful, false otherwise.

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • offset (Integer) —

    the character offset of the new caret position

Returns:

  • (Boolean) —

    true if successful, false otherwise.

#set_selection(text, selection_num, start_offset, end_offset) ⇒ Boolean

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

Parameters:

  • text (Atk::Text) —

    an Atk::Text

  • selection_num (Integer) —

    The selection number. The selected regions are

  • start_offset (Integer) —

    the new starting character offset of the selection

  • end_offset (Integer) —

    the new end position of (e.g. offset immediately past)

Returns:

  • (Boolean) —

    true if successful, false otherwise

#text_attributes_changed(text) ⇒ nil

Parameters:

Returns:

  • (nil)

#text_caret_moved(text, location) ⇒ nil

Parameters:

Returns:

  • (nil)

#text_changed(text, position, length) ⇒ nil

Parameters:

  • text (Atk::Text)
  • position (Integer)
  • length (Integer)

Returns:

  • (nil)

#text_selection_changed(text) ⇒ nil

Parameters:

Returns:

  • (nil)