13.4. Text Iters
Prev | Chapter 13. TextView Widget | Next

## 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_color | background color
fg_color | foreground color
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
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 `TextIter`s can be determined with the method:

      are_equal = lhs.equal(rhs)

Two `TextIter`s 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 `TextIter`s 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

`TextIter`s 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 `TextIter`s 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.

Prev | Up | Next
13.3. Text Buffers | Home | 13.5. Text Marks