Gtk2::TextIters Gtk2::TextIters represent a position between two characters in a Gtk2::TextBuffer. Gtk2::TextIters are usually created by using a Gtk2::TextBuffer method. Gtk2::TextIters are invalidated when the number of characters in a Gtk2::TextBuffer is changed (except for the Gtk2::TextIter that is used for the insertion or deletion). Inserting or deleting pixbufs or anchors also counts as a Gtk2::TextIter invalidating change.
There are a large number of methods associated with a Gtk2::TextIter object. They are grouped together in the following sections by similar function.
Gtk2::TextIter Attributes The Gtk2::TextBuffer that contains the Gtk2::TextIter can be retrieved using the method:
textbuffer = $iter->get_bufferThe following methods can be used to get the location of the
Gtk2::TextIter in the Gtk2::TextBuffer:
integer = $iter->get_offset # returns offset in buffer of iter integer = $iter->get_line # returns number of line at iter integer = $iter->get_line_offset # returns iter offset in line integer = $iter->get_chars_in_line # returns number of chars in line
Gtk2::TextIter The Gtk2::Pango::Language used at a given iter location in the Gtk2::TextBuffer is obtained by calling the method:
language = $iter->get_languageThe more general method used to get the text attributes at a
Gtk2::TextIter's location is:
textattributes = $iter->get_attributeswhere textattributes indicates whether the given values (Gtk2::TextAttributes object) were modified.
Various amounts of text and Gtk2::TextBuffer objects can be retrieved from a Gtk2::TextBuffer using the following methods:
character = $iter->get_char # returns char or 0 if at end of buffer string = $start->get_slice ($end) # returns the text between $start and $end iters string = $start->get_text ($end) # returns the text between $start and $end iters pixbuf or undef = $iter->get_pixbuf # returns the pixbuf at the location (or undef) textchildanchor or undef = $iter->get_child_anchor # returns the child anchor (or undef) list = $iter->get_marks #Returns a list of all Gtk2::TextMark at this location. Because marks are not iterable (they don't take up any #"space" in the buffer, they are just marks in between iterable locations), multiple marks can exist in the same #place. The returned list is not in any meaningful order. list = $iter->get_toggled_tags ($toggled_on) * $toggled_on (boolean) #Returns a list of Gtk2::TextTag that are toggled on or off at this point. (If toggled_on is TRUE, the list contains #tags that are toggled on.) If a tag is toggled on at iter, then some non-empty range of characters following iter #has that tag applied to it. If a tag is toggled off, then some non-empty range following iter does not have the tag #applied to it. list = $iter->get_tags # returns a prioritized list of tags
Gtk2::TextIter Tag conditions at the Gtk2::TextIter location can be checked using the following methods:
boolean = $iter->begins_tag ($tag) * $tag (Gtk2::TextTag or undef) boolean = $iter->ends_tag ($tag) * $tag (Gtk2::TextTag or undef) boolean = $iter->toggles_tag ($tag) * $tag (Gtk2::TextTag or undef) boolean = $iter->has_tag ($tag)These methods return TRUE if the given tag satisfies the condition at iter. If the tag is undef for the first three methods then the result is TRUE if any tag satisfies the condition at iter.
The following methods indicate whether the text at the Gtk2::TextIter location is editable or allows text insertion:
boolean = $iter->editable ($default_setting) * $default_setting (boolean) boolean = $iter->can_insert ($default_editability) * $default_editability (boolean)The
editable method indicates whether the iter is in an editable range of text while the can_insert method indicates whether text can be inserted at iter considering the default editability of the Gtk2::TextView, Gtk2::TextBuffer and applicable tags. The default_editability is usually determined by calling the method:
boolean = $text_view->get_editableTo determine whether a
Gtk2::TextIter is located between two given Gtk2::TextIters use the method:
boolean = $iter->in_range ($start, $end) * $start (Gtk2::TextIter) * $end (Gtk2::TextIter)
The location of a Gtk2::TextIter with respect to the text in a Gtk2::TextBuffer can be determined by the following methods:
boolean = $iter->starts_word boolean = $iter->ends_word boolean = $iter->inside_word boolean = $iter->starts_sentence boolean = $iter->ends_sentence boolean = $iter->inside_sentence boolean = $iter->starts_line boolean = $iter->ends_lineReturns TRUE if the
Gtk2::TextIter is at the given text location. These methods are somewhat self-explanatory. The definition of the text components and their boundaries is determined by the language used at the Gtk2::TextIter. Note that a line is a collection of sentences similar to a paragraph.
The following methods can be used to determine if a Gtk2::TextIter is at the start or end of the Gtk2::TextBuffer
boolean = $iter->is_start boolean = $iter->is_endboolean is TRUE if the
Gtk2::TextIter is at the start or end of the Gtk2::TextBuffer.
Since a Gtk2::TextBuffer may contain multiple characters which are effectively viewed as one cursor position (e.g. carriage return-linefeed combination or letter with an accent mark) it's possible that a Gtk2::TextIter could be in a location which is not a cursor position. The following method indicates whether a Gtk2::TextIter is at a cursor position:
boolean = $iter->is_cursor_position
Gtk2::TextIters can be moved through a Gtk2::TextBuffer in various text unit strides. The definition of the text units is set by the PangoLanguage in use at the Gtk2::TextIter location. The basic methods are:
boolean = $iter->forward_char # forward by one character boolean = $iter->backward_char # backward by one character boolean = $iter->forward_word_end # forward to the end of the word boolean = $iter->backward_word_start # backward to the start of the word boolean = $iter->forward_sentence_end # forward to the end of the sentence boolean = $iter->backward_sentence_start # backward to the start of the sentence boolean = $iter->forward_line # forward to the start of the next line boolean = $iter->backward_line # backward to the start of the previous line boolean = $iter->forward_to_line_end # forward to the end of the line boolean = $iter->forward_cursor_position # forward by one cursor position boolean = $iter->backward_cursor_position # backward by one cursor positionresult is TRUE if the
Gtk2::TextIter was moved and FALSE if the Gtk2::TextIter is at the start or end of the Gtk2::TextBuffer.
All of the above methods (except forward_to_line_end) have corresponding methods that take a count (that can be positive or negative) to move the Gtk2::TextIter in multiple text unit strides:
boolean = $iter->forward_chars ($count) boolean = $iter->backward_chars ($count) boolean = $iter->forward_word_ends ($count) boolean = $iter->backward_word_starts ($count) boolean = $iter->forward_sentence_ends ($count) boolean = $iter->backward_sentence_starts ($count) boolean = $iter->forward_lines ($count) boolean = $iter->backward_lines ($count) boolean = $iter->forward_cursor_positions ($count) boolean = $iter->backward_cursor_positions ($count)
A TextIter can be moved to a specific location in the Gtk2::TextBuffer using the following methods:
$iter->set_offset ($char_offset) # move to given character offset $iter->set_line ($line_number) # move to start of given line $iter->set_line_offset ($char_on_line) # move to given character offset in current line $iter->forward_to_end # move to end of the bufferIn addition, a
Gtk2::TextIter can be moved to a location where a tag is toggled on or off by using the methods:
boolean = $iter->forward_to_tag_toggle ($tag) boolean = $iter->backward_to_tag_toggle ($tag)result is TRUE if the
Gtk2::TextIter was moved to a new location where tag is toggled. If tag is undef then the Gtk2::TextIter will be moved to the next location where any tag is toggled.
A search for a string in a Gtk2::TextBuffer is done using the methods:
(match_start, match_end) = $iter->forward_search ($str, $flags, $limit=NULL) *$str (string) *$flags (Gtk2::TextSearchFlags) *$limit (Gtk2::TextIter or undef) (match_start, match_end) = $iter->backward_search ($str, $flags, $limit=NULL) *$str (string) *$flags (Gtk2::TextSearchFlags) *$limit (Gtk2::TextIter or undef)The return value is a tuple containing
Gtk2::TextIters that indicate the location of the first character of the match and the first character after the match. $str is the character string to be located. $flags modifies the conditions of the search. Gtk2::TextSearchFlags values can be:
*'visible-only' / 'GTK_TEXT_SEARCH_VISIBLE_ONLY' *'text-only' / 'GTK_TEXT_SEARCH_TEXT_ONLY'$limit is an optional
Gtk2::TextIter that bounds the search range.