13.4. Text Iters

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.

13.4.1. TextIter Attributes

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

13.4.2. Text Attributes at a TextIter

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_colorbackground color
fg_colorforeground color
bg_stipplebackground stipple bitmap
fg_stippleforeground stipple bitmap
riseoffset of text above baseline
underlinestyle of underline
strikethroughwhether text is strikethrough
draw_bgTRUE if some tags affect the drawing of the background
justificationstyle of justification
directionwhich direction the text runs
fontPangoFontDescription in use
font_scalescale of the font in use
left_marginlocation of left margin
right_marginlocation of right margin
pixels_above_linespixels spacing above a line
pixels_below_linespixel spacing below a line
pixels_inside_wrappixel spacing between wrapped lines
tabsPangoTabArray in use
wrap_modemode of wrap in use
languagePangoLanguage in use
invisiblewhether text is invisible (not implemented in GTK+ 2.0)
bg_full_heightwhether background is fit to full line height
editablewhether the text is editable
realizedtext is realized
pad1 
pad2 
pad3 
pad4 

13.4.3. Copying a TextIter

A TextIter can be duplicated using the method:

  iter_copy = iter.copy()

13.4.4. Retrieving Text and Objects

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

13.4.5. Checking Conditions at a TextIter

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:

  first.order(second)

which will reorder the TextIter offsets so that first is before second.

13.4.6. Checking Location in Text

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

13.4.7. Moving Through Text

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)

13.4.8. Moving to a Specific Location

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.

13.4.9. Searching in Text

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.