TextIters represent a position between two characters in a TextBuffer. TextIters are usually created by using a TextBuffer method. TextIters are invalidated when the number of characters in a TextBuffer is changed (except for the TextIter that is used for the insertion or deletion). Inserting or deleting pixbufs or anchors also counts as a TextIter invalidating change.
There are a large number of methods associated with a TextIter object. They are grouped together in the following sections by similar function.
The TextBuffer that contains the TextIter can be retrieved using the method:
buffer = iter.get_buffer()
The following methods can be used to get the location of the TextIter in the TextBuffer:
offset = iter.get_offset() # returns offset in buffer of iter line_number = iter.get_line() # returns number of line at iter line_offset = iter.get_line_offset() # returns iter offset in line numchars = iter.get_chars_in_line() # returns number of chars in line
The PangoLanguage used at a given iter location in the TextBuffer is obtained by calling the method:
language = iter.get_language()
The more general method used to get the text attributes at a TextIter's location is:
result = iter.get_attributes(values)
where result indicates whether the given values (TextAttributes object) were modified. The given values are obtained by using the TextView method:
values = textview.get_default_attributes()
The following attributes are accessible from a TextAttributes object (not implemented in PyGTK <= 1.99.15):
|bg_stipple||background stipple bitmap|
|fg_stipple||foreground stipple bitmap|
|rise||offset of text above baseline|
|underline||style of underline|
|strikethrough||whether text is strikethrough|
|draw_bg||TRUE if some tags affect the drawing of the background|
|justification||style of justification|
|direction||which direction the text runs|
|font||PangoFontDescription in use|
|font_scale||scale of the font in use|
|left_margin||location of left margin|
|right_margin||location of right margin|
|pixels_above_lines||pixels spacing above a line|
|pixels_below_lines||pixel spacing below a line|
|pixels_inside_wrap||pixel spacing between wrapped lines|
|tabs||PangoTabArray in use|
|wrap_mode||mode of wrap in use|
|language||PangoLanguage in use|
|invisible||whether text is invisible (not implemented in GTK+ 2.0)|
|bg_full_height||whether background is fit to full line height|
|editable||whether the text is editable|
|realized||text is realized|
Various amounts of text and TextBuffer objects can be retrieved from a TextBuffer using the following methods:
char = iter.get_char() # returns char or 0 if at end of buffer text = start.get_slice(end) # returns the text between start and end iters text = start.get_text(end) # returns the text between start and end iters pixbuf = iter.get_pixbuf() # returns the pixbuf at the location (or None) anchor = iter.get_child_anchor() # returns the child anchor (or None) mark_list = iter.get_marks() # returns a list of marks tag_list = iter.get_toggled_tags() # returns a list of tags that are toggled on or off tag_list = iter.get_tags() # returns a prioritized list of tags
Tag conditions at the TextIter location can be checked using the following methods:
result = iter.begins_tag(tag=None) # TRUE if tag is toggled on at iter result = iter.ends_tag(tag=None) # TRUE if tag is toggled off at iter result = iter.toggles_tag(tag=None) # TRUE if tag is toggled on or off at iter result = iter.has_tag(tag) # TRUE if tag is active at iter
These methods return TRUE if the given tag satisfies the condition at iter. If the tag is None 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 TextIter location is editable or allows text insertion:
result = iter.editable() result = iter.can_insert(default_editability)
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 TextView, TextBuffer and applicable tags. The default_editability is usually determined by calling the method:
default_editability = textview.get_editable()
The equivalence of two TextIters can be determined with the method:
are_equal = lhs.equal(rhs)
Two TextIters can be compared with the method:
result = lhs.compare(rhs)
result will be: -1 if lhs is less than rhs; 0 if lhs equals rhs; and, 1 if lhs is greater than rhs.
To determine whether a TextIter is located between two given TextIters use the method:
result = iter.in_range(start, end)
result is TRUE if iter is between start and end. Note: start and end must be in ascending order. This can be guaranteed using the method:
which will reorder the TextIter offsets so that first is before second.
The location of a TextIter with respect to the text in a TextBuffer can be determined by the following methods:
result = iter.starts_word() result = iter.ends_word() result = iter.inside_word() result = iter.starts_sentence() result = iter.ends_sentence() result = iter.inside_sentence() result = starts_line() result = iter.ends_line()
result returns TRUE if the 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 TextIter. Note that a line is a collection of sentences similar to a paragraph.
The following methods can be used to determine if a TextIter is at the start or end of the TextBuffer:
result = iter.is_start() result = iter.is_end()
result is TRUE if the TextIter is at the start or end of the TextBuffer.
Since a 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 TextIter could be in a location which is not a cursor position. The following method indicates whether a TextIter is at a cursor position:
result = iter.is_cursor_position()
TextIters can be moved through a TextBuffer in various text unit strides. The definition of the text units is set by the PangoLanguage in use at the TextIter location. The basic methods are:
result = iter.forward_char() # forward by one character result = iter.backward_char() # backward by one character result = iter.forward_word_end() # forward to the end of the word result = iter.backward_word_start() # backward to the start of the word result = iter.forward_sentence_end() # forward to the end of the sentence result = iter.backward_sentence_start() # backward to the start of the sentence result = iter.forward_line() # forward to the start of the next line result = iter.backward_line() # backward to the start of the previous line result = iter.forward_to_line_end() # forward to the end of the line result = iter.forward_cursor_position() # forward by one cursor position result = iter.backward_cursor_position() # forward by one cursor position
result is TRUE if the TextIter was moved and FALSE if the TextIter is at the start or end of the 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 TextIter in multiple text unit strides:
result = iter.forward_chars(count) result = iter.backward_chars(count) result = iter.forward_word_ends(count) result = iter.backward_word_starts(count) result = iter.forward_sentence_ends(count) result = iter.backward_sentence_starts(count) result = iter.forward_lines(count) result = iter.backward_lines(count) result = iter.forward_cursor_positions(count) result = iter.backward_cursor_positions(count)
A TextIter can be moved to a specific location in the 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 buffer
In addition, a TextIter can be moved to a location where a tag is toggled on or off by using the methods:
result = iter.forward_to_tag_toggle(tag) result = iter.backward_to_tag_taoggle(tag)
result is TRUE if the TextIter was moved to a new location where tag is toggled. If tag is None then the TextIter will be moved to the next location where any tag is toggled.
A search for a string in a TextBuffer is done using the methods:
match_start, match_end = iter.forward_search(str, flags, limit=None) match_start, match_end = iter.backward_search(str, flags, limit=None)
The return value is a tuple containing 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; flag values can be:
gtk.TEXT_SEARCH_VISIBLE_ONLY # invisible characters are ignored gtk.TEXT_SEARCH_TEXT_ONLY # pixbufs and child anchors are ignored
limit is an optional TextIter that bounds the search range.