gtk.TextIter
Prev | The gtk Class Reference | Next

## gtk.TextIter

gtk.TextIter — an object pointing at a location in a `gtk.TextBuffer`

## Synopsis

    class gtk.TextIter(gobject.GBoxed):
        def get_buffer()
        def copy()
        def get_offset()
        def get_line()
        def get_line_offset()
        def get_line_index()
        def get_visible_line_offset()
        def get_visible_line_index()
        def get_char()
        def get_slice(end)
        def get_text(end)
        def get_visible_slice(end)
        def get_visible_text(end)
        def get_pixbuf()
        def get_marks()
        def get_child_anchor()
        def get_toggled_tags(toggled_on)
        def begins_tag(tag=None)
        def ends_tag(tag=None)
        def toggles_tag(tag=None)
        def has_tag(tag)
        def get_tags()
        def editable(default_setting)
        def can_insert(default_editability)
        def starts_word()
        def ends_word()
        def inside_word()
        def starts_sentence()
        def ends_sentence()
        def inside_sentence()
        def starts_line()
        def ends_line()
        def is_cursor_position()
        def get_chars_in_line()
        def get_bytes_in_line()
        def get_attributes(values)
        def get_language()
        def is_end()
        def is_start()
        def forward_char()
        def backward_char()
        def forward_chars(count)
        def backward_chars(count)
        def forward_line()
        def backward_line()
        def forward_lines(count)
        def backward_lines(count)
        def forward_word_ends(count)
        def backward_word_starts(count)
        def forward_word_end()
        def backward_word_start()
        def forward_cursor_position()
        def backward_cursor_position()
        def forward_cursor_positions(count)
        def backward_cursor_positions(count)
        def backward_sentence_start()
        def forward_sentence_end()
        def backward_sentence_starts(count)
        def forward_sentence_ends(count)
        def forward_visible_word_ends(count)
        def backward_visible_word_starts(count)
        def forward_visible_word_end()
        def backward_visible_word_start()
        def forward_visible_cursor_position()
        def backward_visible_cursor_position()
        def forward_visible_cursor_positions(count)
        def backward_visible_cursor_positions(count)
        def forward_visible_line()
        def backward_visible_line()
        def forward_visible_lines(count)
        def backward_visible_lines(count)
        def set_offset(char_offset)
        def set_line(line_number)
        def set_line_offset(char_on_line)
        def set_line_index(byte_on_line)
        def forward_to_end()
        def forward_to_line_end()
        def set_visible_line_offset(char_on_line)
        def set_visible_line_index(byte_on_line)
        def forward_to_tag_toggle(tag)
        def backward_to_tag_toggle(tag)
        def forward_find_char(pred, user_data, limit)
        def backward_find_char(pred, user_data, limit)
        def forward_search(str, flags, limit=None)
        def backward_search(str, flags, limit=None)
        def equal(rhs)
        def compare(rhs)
        def in_range(start, end)
        def order(second)

## Description

A `gtk.TextIter` points to a position between two characters in a `gtk.TextBuffer`. A `gtk.TextIter` is usually created using a `gtk.TextBuffer` method and are invalidated when the number of characters in the `gtk.TextBuffer` changes (with some exceptions when inserting or deleting) including inserting or deleting pixbufs or child anchors. There are a huge number of `gtk.TextIter` methods mostly dealing with moving the textiter location in the textbuffer, checking the location or retrieving text or objects at a location.

## Methods

### gtk.TextIter.get_buffer

        def get_buffer()

Returns : | the textbuffer

The `get_buffer`() method returns the `gtk.TextBuffer` object this iterator is associated with.

### gtk.TextIter.copy

        def copy()

Returns : | a copy of the textiter

The `copy`() method creates a copy of the textiter.

### gtk.TextIter.get_offset

        def get_offset()

Returns : | a character offset

The `get_offset`() method returns the character offset of the textiter. Each character in a `gtk.TextBuffer` has an offset, starting with 0 for the first character in the textbuffer. Use `gtk.TextBuffer.get_iter_at_offset`() to convert an offset back into a textiter.

### gtk.TextIter.get_line

        def get_line()

Returns : | a line number

The `get_line`() method returns the line number containing the textiter. Lines in a `gtk.TextBuffer` are numbered beginning with 0 for the first line.

### gtk.TextIter.get_line_offset

        def get_line_offset()

Returns : | the offset from the start of the line

The `get_line_offset`() method returns the character offset of the textiter location, counting from the start of the line containing the textiter location. The first character on the line has offset 0.

### gtk.TextIter.get_line_index

        def get_line_index()

Returns : | the number of bytes from the start of the line

The `get_line_offset`() method returns the byte index of the textiter location, counting from the start of the line containing the textiter location. Remember that `gtk.TextBuffer` encodes text in UTF-8, and that characters can require a variable number of bytes to represent.

### gtk.TextIter.get_visible_line_offset

        def get_visible_line_offset()

Returns : | the offset in visible characters from the start of the line

The `get_visible_line_offset`() method returns the offset in characters of the textiter location from the start of the line containing the textiter location, not counting characters that are invisible due to tags with the "invisible" attribute set.

### gtk.TextIter.get_visible_line_index

        def get_visible_line_index()

Returns : | a byte index from the start of the line

The `get_visible_line_index`() method returns the byte index of the textiter location from the start of the line, not counting bytes that are invisible due to tags with the "invisible" attribute set.

### gtk.TextIter.get_char

        def get_char()

Returns : | a Unicode character, or 0 if the textiter is not dereferenceable

The `get_char`() method returns the Unicode character at this textiter location. If the textiter points at a non-character element, such as an image embedded in the buffer, the Unicode "unknown" character 0xFFFC is returned. If invoked on the end textiter, zero is returned; zero is not a valid Unicode character. So you can write a loop which ends when the `get_char`() method returns 0.

### gtk.TextIter.get_slice

        def get_slice(end)

`end` : | the textiter at the end of a range
Returns : | a slice of text from the textbuffer

The `get_slice`() method returns the text in the range between the locations specified by the textiter and `end`. A "slice" is an array of characters encoded in UTF-8 format, including the Unicode "unknown" character 0xFFFC for iterable non-character elements in the textbuffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned array will correspond to byte offsets in the textbuffer. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget is in the textbuffer.

### gtk.TextIter.get_text

        def get_text(end)

`end` : | textiter at end of a range
Returns : | array of characters from the buffer

The `get_text`() method returns the text in the range between the locations specified by the textiter and `end`. If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the textbuffer. If you want the offsets to correspond, use the `get_slice`() method.

### gtk.TextIter.get_visible_slice

        def get_visible_slice(end)

`end` : | textiter at end of range
Returns : | a slice of visible text from the textbuffer

The `get_visible_slice`() method is similar to the `get_slice`() method, but invisible text is excluded. Invisible text is text with the "invisible" attribute set on it.

### gtk.TextIter.get_visible_text

        def get_visible_text(end)

`end` : | textiter at end of range
Returns : | a string containing visible text from the textbuffer

The `get_visible_text`() method is similar to the `get_text`(), but invisible text is excluded. Invisible text is text with the "invisible" attribute set on it.

### gtk.TextIter.get_pixbuf

        def get_pixbuf()

Returns : | a pixbuf or `None`

The `get_pixbuf`() method returns the `gtk.gdk.Pixbuf` object at the textiter location, if any; otherwise, `None` is returned.

### gtk.TextIter.get_marks

        def get_marks()

Returns : | a list of `gtk.TextMark` objects

The `get_marks`() method returns a list of all `gtk.TextMark` objects at the textiter location. Because marks don't take up any "space" in the buffer, multiple marks can exist in the same location. The returned list is not in any meaningful order.

### gtk.TextIter.get_child_anchor

        def get_child_anchor()

Returns : | a child anchor or `None`

The `get_child_anchor`() method returns the `gtk.TextChildAnchor` at the textiter location, if any; otherwise, `None` is returned.

### gtk.TextIter.get_toggled_tags

        def get_toggled_tags(toggled_on)

`toggled_on` : | if `TRUE` get toggled-on tags; otherwise get toggle-off tags
Returns : | a list of tags toggled at this point

The `get_toggled_tags`() method returns a list of `gtk.TextTag` objects 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 the textiter location, some non-empty range of characters following the textiter has that tag applied to it. If a tag is toggled off, then some non-empty range following the textiter location does not have the tag applied to it.

### gtk.TextIter.begins_tag

        def begins_tag(tag=None)

`tag` : | a `gtk.TextTag`, or `None`
Returns : | `TRUE` if the textiter is the start of a range tagged with `tag`

The `begins_tag`() method returns `TRUE` if `tag` is toggled on at exactly this point. If `tag` is `None`, this method returns `TRUE` if any tag is toggled on at this point. Note that the`begins_tag`() method returns `TRUE` only if the textiter location is the start of the tagged range; the `has_tag`() indicates if a textiter location is within a tagged range.

### gtk.TextIter.ends_tag

        def ends_tag(tag=None)

`tag` : | a `gtk.TextTag`, or `None`
Returns : | `TRUE` if the textiter is the end of a range tagged with `tag`

The `ends_tag`() method returns `TRUE` if `tag` is toggled off at the location the textiter points to. If `tag` is `None`, this method returns `TRUE` if any tag is toggled off at this point. Note that the `ends_tag`() returns `TRUE` only if the textiter location is the end of the tagged range; the `has_tag`() indicates if a textiter location is within a tagged range.

### gtk.TextIter.toggles_tag

        def toggles_tag(tag=None)

`tag` : | a `gtk.TextTag`, or `None`
Returns : | `TRUE` if `tag` is toggled on or off at the textiter location

The `toggles_tag`() method returns `TRUE` if a range of text with `tag` applied to it begins or ends at the textiter location. If `tag` is `None` this method returns `TRUE` if any tag begins or ends at the textiter location.

### gtk.TextIter.has_tag

        def has_tag(tag)

`tag` : | a `gtk.TextTag`
Returns : | `TRUE` if the textiter location is tagged with `tag`

The `has_tag`() method returns `TRUE` if the textiter location is within a range of text tagged with `tag`.

### gtk.TextIter.get_tags

        def get_tags()

Returns : | a list of `gtk.TextTag` objects

The `get_tags`() method returns a list of tags that apply to the textiter location, in ascending order of priority (highest-priority tags are last).

### gtk.TextIter.editable

        def editable(default_setting)

`default_setting` : | if `TRUE` the text is editable by default
Returns : | `TRUE` if the textiter location is inside an editable range or text

The `editable`() method returns `TRUE` if the character at the textiter location is within an editable range of text. Non-editable text is "locked" and can't be changed by the user via a `gtk.TextView`. This method is a convenience wrapper around the `get_attributes`() method. If no tags applied to this text location affect editability, the value of `default_setting` will be returned.

Do not use this method to determine if text can be inserted at the textiter location. For insertion you don't want to know if the char at the textiter location is inside an editable range of text, you want to know whether a new character inserted at the textiter location would be inside an editable range of text. Use the `can_insert`() method to determine if text can be inserted.

### gtk.TextIter.can_insert

        def can_insert(default_editability)

`default_editability` : | if `TRUE` the text is editable by default
Returns : | `TRUE` if text inserted at `iter` would be editable

The `can_insert`() method considers the default editability of the buffer, and the tags that affect editability, to determine if text inserted at the textiter location would be editable. If so, the user should be allowed to insert text at the textiter location. The `gtk.TextBuffer.insert_interactive`() uses this function to determine if insertions are allowed at a given position.

### gtk.TextIter.starts_word

        def starts_word()

Returns : | `TRUE` if the textiter location is at the start of a word

The `starts_word`() method returns `TRUE` if the textiter location begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

### gtk.TextIter.ends_word

        def ends_word()

Returns : | `TRUE` if the textiter location is at the end of a word

The `ends_word`() method returns `TRUE` if the textiter location ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

### gtk.TextIter.inside_word

        def inside_word()

Returns : | `TRUE` if the textiter location is inside a word

The `inside_word`() method returns `TRUE` if the textiter location is inside a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

### gtk.TextIter.starts_sentence

        def starts_sentence()

Returns : | `TRUE` if the textiter location is at the start of a sentence.

The `starts_sentence`() method returns `TRUE` if the textiter location begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

### gtk.TextIter.ends_sentence

        def ends_sentence()

Returns : | `TRUE` if the textiter location is at the end of a sentence.

The `ends_sentence`() method returns `TRUE` if the textiter location ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

### gtk.TextIter.inside_sentence

        def inside_sentence()

Returns : | `TRUE` if the textiter location is inside a sentence.

The `inside_sentence`() method returns `TRUE` if the textiter location is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

### gtk.TextIter.starts_line

        def starts_line()

Returns : | `TRUE` if the textiter location begins a line

The `starts_line`() method returns `TRUE` if the textiter location begins a paragraph, i.e. if the `.get_line_offset`() method would return 0.

### gtk.TextIter.ends_line

        def ends_line()

Returns : | `TRUE` if the textiter location is at the end of a line

The `ends_line`() method returns `TRUE` if the textiter location points to the start of the paragraph delimiter characters for a line (delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character). Note that an textiter pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end textiter is considered to be at the end of a line, even though there are no paragraph delimiter chars there.

### gtk.TextIter.is_cursor_position

        def is_cursor_position()

Returns : | `TRUE` if the cursor can be placed at the textiter location

The `is_cursor_position`() method returns `TRUE` if the cursor can be placed at the textiter location. See the `forward_cursor_position`() method for details on what a cursor position is.

### gtk.TextIter.get_chars_in_line

        def get_chars_in_line()

Returns : | the number of characters in the line

The `get_chars_in_line`() method returns the number of characters in the line containing the textiter location, including the paragraph delimiters.

### gtk.TextIter.get_bytes_in_line

        def get_bytes_in_line()

Returns : | the number of bytes in the line

The `get_bytes_in_line`() method returns the number of bytes in the line containing the textiter location, including the paragraph delimiters.

### gtk.TextIter.get_attributes

        def get_attributes(values)

`values` : | a `gtk.TextAttributes` object to be filled in
Returns : | `TRUE` if `values` was modified

The `get_attributes`() method computes the effect of any tags applied to the textiter location and applies those attributes to the `gtk.TextAttributes` object specified by `values` (which should be initialized to the default settings you wish to use if no tags are in effect). Typically the default attributes are obtained from the `gtk.TextView.get_default_attributes`() method. If any tags affected `values`, the method returns `TRUE`.

### gtk.TextIter.get_language

        def get_language()

Returns : | the pango language in effect at the textiter location

The `get_language`() method is a convenience wrapper around the `get_attributes`() method, that returns the language in effect at the textiter location. If no tags affecting language apply to the textiter location, the return value is identical to that of the `gtk.get_default_language()` function.

### gtk.TextIter.is_end

        def is_end()

Returns : | `TRUE` if the textiter is the end textiter

The `is_end`() method returns `TRUE` if the textiter is the end textiter, i.e. one past the last dereferenceable textiter in the buffer. The `is_end`() method is the most efficient way to check whether an textiter is the end textiter.

### gtk.TextIter.is_start

        def is_start()

Returns : | `TRUE` if the textiter location is at the start of the textbuffer

The `is_start`() method returns `TRUE` if the textiter location is at the start of the textbuffer, that is if the textiter location has a character offset of 0.

### gtk.TextIter.forward_char

        def forward_char()

Returns : | `TRUE` if the textiter location moved and is dereferenceable

The `forward_char`() method moves the textiter location forward by one character offset and returns `TRUE` if the textiter location moved and the new location is dereferenceable. Note that images embedded in the buffer occupy 1 character slot, so the `forward_char`() method may actually move onto an image instead of a character, if you have images in your buffer. If the textiter location is the end textiter or one character before it, the textiter location will now point at the end textiter, and the `forward_char`() method returns `FALSE`.

### gtk.TextIter.backward_char

        def backward_char()

Returns : | TRUE if the textiter location moved and is not the start textiter

The `backward_char`() method moves the textiter location backward by one character offset and returns `TRUE` if the textiter location moved. If the old textiter location was the first in the buffer (character offset 0), the `backward_char`() method returns `FALSE`.

### gtk.TextIter.forward_chars

        def forward_chars(count)

`count` : | the number of characters to move, may be negative
Returns : | `TRUE` if the textiter location moved and is dereferenceable

The `forward_chars`() method moves the textiter location forward `count` characters if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The `forward_chars`() method returns `TRUE` if the new position of the resulting textiter location is different from its original position, and is dereferenceable (the last textiter in the buffer is not dereferenceable). If `count` is 0, the function does nothing and returns `FALSE`.

### gtk.TextIter.backward_chars

        def backward_chars(count)

`count` : | the number of characters to move, may be negative
Returns : | `TRUE` if the textiter location moved and is dereferenceable

The `backward_chars`() method moves the textiter location backward forward `count` characters, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The `backward_chars`() method returns `TRUE` if the new position of the resulting textiter location is different from its original position, and is dereferenceable (the last textiter in the buffer is not dereferenceable). If `count` is 0, the function does nothing and returns `FALSE`.

### gtk.TextIter.forward_line

        def forward_line()

Returns : | `TRUE` if the textiter location can be dereferenced

The `forward_line`() method moves the textiter location to the start of the next line and returns `TRUE` if the textiter location moved to a dereferenceable position, and `FALSE` if the textiter location moved to the end of the buffer, or if the textiter location was originally at the end of the buffer.

### gtk.TextIter.backward_line

        def backward_line()

Returns : | `TRUE` if the textiter location moved

The `backward_line`() method moves the textiter location to the start of the previous line and returns `TRUE` if the textiter location was moved. If the textiter location was at the textbuffer start, this method returns `FALSE`. For example if the textiter location was already on line 0, but not at the start of the line, the textiter location is snapped to the start of the line and the method returns `TRUE`.

### gtk.TextIter.forward_lines

        def forward_lines(count)

`count` : | the number of lines to move forward, may be negative
Returns : | `TRUE` if the textiter location moved and is dereferenceable

The `forward_lines`() method moves the textiter location forward `count` lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

- `TRUE` if the textiter moved to a dereferenceable position; or,
- `FALSE` if the textiter location didn't move, or moved onto the end textiter or if `count` was 0.

If `count` is negative, the textiter location moves backward by `count` lines.

### gtk.TextIter.backward_lines

        def backward_lines(count)

`count` : | the number of lines to move backward, may be negative
Returns : | `TRUE` if the textiter location moved to a dereferenceable position

The `backward_lines`() method moves the textiter location backward by `count` lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

- `TRUE` if the textiter moved to a dereferenceable position; or,
- `FALSE` if the textiter location didn't move, or moved onto the end textiter or if `count` was 0.

If `count` is negative, the textiter location moves forward by `count` lines.

### gtk.TextIter.forward_word_ends

        def forward_word_ends(count)

`count` : | the number of times to move
Returns : | `TRUE` if the textiter location moved and is not the end textiter

The `forward_word_ends`() method calls the `forward_word_end`() method up to `count` times or the `backward_word_starts`() method if `count` is negative. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.backward_word_starts

        def backward_word_starts(count)

`count` : | the number of times to move
Returns : | `TRUE` if the textiter location moved and is not the end textiter

The `backward_word_starts(`) method calls the `backward_word_start`() method up to `count` times or the `forward_word_ends`() method if `count` is negative. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.forward_word_end

        def forward_word_end()

Returns : | `TRUE` if the textiter location moved to a dereferenceable position

The `forward_word_end`() method moves the textiter location forward to the next word end. If the textiter location is currently on a word end, the location moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). The method returns TRUE if the textiter location moved to a dereferenceable position

### gtk.TextIter.backward_word_start

        def backward_word_start()

Returns : | `TRUE` if the textiter location moved

The `backward_word_start`() method moves the textiter location backward to the previous word start. If the textiter location is currently on a word start, the location moves backward to the next one before that. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). The method returns `TRUE` if the textiter location moved.

### gtk.TextIter.forward_cursor_position

        def forward_cursor_position()

Returns : | `TRUE` if we moved and the new position is dereferenceable

The `forward_cursor_position`() method moves the textiter location forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can't go between those two characters. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.backward_cursor_position

        def backward_cursor_position()

Returns : | `TRUE` if we moved and the new position is dereferenceable

The `backward_cursor_position`() method is similar to the `forward_cursor_position`() method, except the location moves backward.

### gtk.TextIter.forward_cursor_positions

        def forward_cursor_positions(count)

`count` : | the number of positions to move
Returns : | `TRUE` if the textiter location moved and the new position is dereferenceable

The `forward_cursor_positions`() method moves up to `count` cursor positions. See the `forward_cursor_position`() method for more details. The method returns `TRUE` if the textiter moved to a dereferenceable location.

### gtk.TextIter.backward_cursor_positions

        def backward_cursor_positions(count)

`count` : | the number of positions to move
Returns : | `TRUE` if the textiter location moved and the new position is dereferenceable

The `backward_cursor_positions`() method moves the textiter location up to `count` cursor positions. See the `forward_cursor_position`() method for details.

### gtk.TextIter.backward_sentence_start

        def backward_sentence_start()

Returns : | `TRUE` if the textiter location moved

The `backward_sentence_start`() method moves the textiter location backward to the previous sentence start. If the textiter location is already at the start of a sentence, the location moves backward to the next one. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

### gtk.TextIter.forward_sentence_end

        def forward_sentence_end()

Returns : | `TRUE` if the textiter location moved and is not the end textiter

The `forward_sentence_end`() method moves the textiter location forward to the next sentence end. (If the textiter location is at the end of a sentence, the location moves to the next end of sentence.) Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.backward_sentence_starts

        def backward_sentence_starts(count)

`count` : | the number of sentences to move
Returns : | `TRUE` if the textiter location moved and is not the end textiter

The `backward_sentence_starts`() method calls the `backward_sentence_start`() method (or the `forward_sentence_end`()() method if count is negative) up to `count` times, or until it returns `FALSE`. If `count` is negative, the location moves forward instead of backward. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.forward_sentence_ends

        def forward_sentence_ends(count)

`count` : | the number of sentences to move
Returns : | `TRUE` if the textiter location moved and is not the end textiter

The `forward_sentence_ends`() method calls the `forward_sentence_end`() method `count` times (or until the `forward_sentence_end`() method returns `FALSE`). If `count` is negative, the location moves backward instead of forward. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.forward_visible_word_ends

        def forward_visible_word_ends(count)

`count` : | the number of times to move
Returns : | `TRUE` if the textiter moved and is not the end iterator

### Note

This method is available in PyGTK 2.4 and above.

The `forward_visible_word_ends`() method calls the `forward_visible_word_end()` method the number of times specified by `count`.

### gtk.TextIter.backward_visible_word_starts

        def backward_visible_word_starts(count)

`count` : | the number of times to move
Returns : | `TRUE` if the textiter moved and is not the end iterator

### Note

This method is available in PyGTK 2.4 and above.

The `backward_visible_word_starts`() method calls the `backward_visible_word_start()` method the number of times specified by `count`.

### gtk.TextIter.forward_visible_word_end

        def forward_visible_word_end()

Returns : | `TRUE` if the textiter moved and is not the end iterator

### Note

This method is available in PyGTK 2.4 and above.

The `forward_visible_word_end`() method moves the textiter forward to the next visible word end. (If the textiter is currently on a word end, it moves forward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

### gtk.TextIter.backward_visible_word_start

        def backward_visible_word_start()

Returns : | `TRUE` if the textiter moved and is not the end iterator

### Note

This method is available in PyGTK 2.4 and above.

The `backward_visible_word_start`() method moves the textiter backward to the previous visible word start. (If textiter is currently on a word start, it moves backward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

### gtk.TextIter.forward_visible_cursor_position

        def forward_visible_cursor_position()

Returns : | `TRUE` if we moved and the new position is dereferenceable

### Note

This method is available in PyGTK 2.4 and above.

The `forward_visible_cursor_position`() method moves the textiter location forward by a single visible cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can't go between those two characters. The method returns `TRUE` if the textiter location changed and the resulting location is not at the end of the textbuffer.

### gtk.TextIter.backward_visible_cursor_position

        def backward_visible_cursor_position()

Returns : | `TRUE` if we moved and the new position is dereferenceable

### Note

This method is available in PyGTK 2.4 and above.

The `backward_visible_cursor_position`() method is similar to the `forward_visible_cursor_position`() method, except the location moves backward.

### gtk.TextIter.forward_visible_cursor_positions

        def forward_visible_cursor_positions(count)

`count` : | the number of positions to move
Returns : | `TRUE` if the textiter location moved and the new position is dereferenceable

### Note

This method is available in PyGTK 2.4 and above.

The `forward_visible_cursor_positions`() method moves up to `count` visible cursor positions. See the `forward_visible_cursor_position`() method for more details. The method returns `TRUE` if the textiter moved to a dereferenceable location.

### gtk.TextIter.backward_visible_cursor_positions

        def backward_visible_cursor_positions(count)

`count` : | the number of positions to move
Returns : | `TRUE` if the textiter location moved and the new position is dereferenceable

### Note

This method is available in PyGTK 2.4 and above.

The `backward_visible_cursor_positions`() method moves the textiter location up to `count` visible cursor positions. See the `forward_visible_cursor_position`() method for details.

### gtk.TextIter.forward_visible_line

        def forward_visible_line()

Returns : | `TRUE` if the textiter location can be dereferenced

### Note

This method is available in PyGTK 2.8 and above.

The `forward_visible_line`() method moves the textiter location to the start of the next visible line and returns `TRUE` if the textiter location moved to a dereferenceable position, and `FALSE` if the textiter location moved to the end of the buffer, or if the textiter location was originally at the end of the buffer.

### gtk.TextIter.backward_visible_line

        def backward_visible_line()

Returns : | `TRUE` if the textiter location moved

### Note

This method is available in PyGTK 2.8 and above.

The `backward_visible_line`() method moves the textiter location to the start of the previous visible line and returns `TRUE` if the textiter location was moved. If the textiter location was at the textbuffer start, this method returns `FALSE`. For example if the textiter location was already on line 0, but not at the start of the line, the textiter location is snapped to the start of the line and the method returns `TRUE`.

### gtk.TextIter.forward_visible_lines

        def forward_visible_lines(count)

`count` : | the number of visible lines to move forward, may be negative
Returns : | `TRUE` if the textiter location moved and is dereferenceable

### Note

This method is available in PyGTK 2.8 and above.

The `forward_visible_lines`() method moves the textiter location forward `count` visible lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

- `TRUE` if the textiter moved to a dereferenceable position; or,
- `FALSE` if the textiter location didn't move, or moved onto the end textiter or if `count` was 0.

If `count` is negative, the textiter location moves backward by `count` visible lines.

### gtk.TextIter.backward_visible_lines

        def backward_visible_lines(count)

`count` : | the number of visible lines to move backward, may be negative
Returns : | `TRUE` if the textiter location moved to a dereferenceable position

### Note

This method is available in PyGTK 2.8 and above.

The `backward_visible_lines`() method moves the textiter location backward by `count` lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

- `TRUE` if the textiter moved to a dereferenceable position; or,
- `FALSE` if the textiter location didn't move, or moved onto the end textiter or if `count` was 0.

If `count` is negative, the textiter location moves forward by `count` visible lines.

### gtk.TextIter.set_offset

        def set_offset(char_offset)

`char_offset` : | a character number

The `set_offset`() method sets the textiter location to point to the location that is `char_offset` counts from the start of the textbuffer (starting with 0).

### gtk.TextIter.set_line

        def set_line(line_number)

`line_number` : | a line number (counted from 0)

The `set_line`() method sets the textiter location to the start of the line specified by `line_number`. If `line_number` is negative or larger than the number of lines in the textbuffer, the method moves the textiter location to the start of the last line in the buffer.

### gtk.TextIter.set_line_offset

        def set_line_offset(char_on_line)

`char_on_line` : | a character offset relative to the start of the textiter location's current line

The `set_line_offset`() method moves the textiter location within a line, to the new character (not byte) offset specified by `char_on_line`. The character offset must be less than or equal to the number of characters in the line; if equal, the textiter location moves to the start of the next line. See the `set_line_index`() method if you have a byte index rather than a character offset.

### gtk.TextIter.set_line_index

        def set_line_index(byte_on_line)

`byte_on_line` : | a byte index relative to the start of the textiter location's current line

The `set_line_index`() method is similar to the `set_line_offset`(), but works with a byte index instead of a character index. The given byte index must be at the start of a character, it can't be in the middle of a UTF-8 encoded character.

### gtk.TextIter.forward_to_end

        def forward_to_end()

The `forward_to_end`() method moves the textiter location forward to the "end textiter," that points one past the last valid character in the buffer. The `get_char`() method called on the end textiter returns 0, which is convenient for writing loops.

### gtk.TextIter.forward_to_line_end

        def forward_to_line_end()

Returns : | `TRUE` if we moved and the new location is not the end textiter

The `forward_to_line_end`() method moves the textiter to point to the paragraph delimiter characters at the end of the current line. The paragraph delimiter characters are a newline, a carriage return, a carriage return-newline in sequence, or the Unicode paragraph separator character. If the textiter is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If the textiter location is on the last line in the buffer, which does not end in paragraph delimiters, moves to the end textiter (end of the last line), and returns `FALSE`.

### gtk.TextIter.set_visible_line_offset

        def set_visible_line_offset(char_on_line)

`char_on_line` : | a character offset

The `set_visible_char_offset`() method is similar to the `set_line_offset`() method, but the offset is in visible characters, i.e. text with the invisible attribute set is not counted in the offset.

### gtk.TextIter.set_visible_line_index

        def set_visible_line_index(byte_on_line)

`byte_on_line` : | a byte index

The `set_visible_line_index`() method is similar to the `set_line_index`() method, but the index is in visible bytes, i.e. text with the attribute set is not counted in the index.

### gtk.TextIter.forward_to_tag_toggle

        def forward_to_tag_toggle(tag)

`tag` : | a `gtk.TextTag`, or `None`
Returns : | `TRUE` if a tag toggle was found after the textiter location

The `forward_to_tag_toggle`() method moves the textiter location forward to the next toggle (on or off) of the `gtk.TextTag` specified by `tag`, or to the next toggle of any tag if `tag` is `None`. If no matching tag toggles are found, this method returns `FALSE` and sets the textiter location to the end of the textbuffer; otherwise, returns `TRUE`. The `forward_to_tag_toggle`() method does not recognize toggles located at the textiter location, only toggles after the textiter location.

### gtk.TextIter.backward_to_tag_toggle

        def backward_to_tag_toggle(tag)

`tag` : | a `gtk.TextTag`, or `None`
Returns : | `TRUE` if a tag toggle was found before the textiter location

The `backward_to_tag_toggle`() method moves the textiter location backward to the next toggle (on or off) of the `gtk.TextTag` specified by `tag`, or to the next toggle of any tag if `tag` is `None`. If no matching tag toggles are found, this method returns `FALSE` and sets the textiter location to the start of the textbuffer; otherwise, returns `TRUE`. The `backward_to_tag_toggle`() method does not recognize toggles located at the textiter location, only toggles before the textiter location.

### gtk.TextIter.forward_find_char

        def forward_find_char(pred, user_data, limit)

`pred` : | a function to be called on each character
`user_data` : | user data for `pred`
`limit` : | a `gtk.TextIter` pointing at a position to end the search, or `None` for the end of the buffer.
Returns : | `TRUE` if a match was found

### Note

This method is available in PyGTK 2.4 and above.

The `forward_find_char`() method advances the textiter, calling the function specified by `pred` on each character. If `pred` returns `TRUE`, `forward_find_char` stops scanning and returns `TRUE`. If `pred` never returns `TRUE`, the textiter location is set to `limit` or the end textiter, if `limit` is `None`.

### Warning

This method is likely to be very slow since the Python function `pred` is called for every character.

### gtk.TextIter.backward_find_char

        def backward_find_char(pred, user_data, limit)

`pred` : | a function to be called on each character
`user_data` : | user data for `pred`
`limit` : | a `gtk.TextIter` pointing at a position to end the search, or `None` for the beginning of the buffer.
Returns : | `TRUE` if a match was found

### Note

This method is available in PyGTK 2.4 and above.

The `backward_find_char`() method is similar to the `forward_find_char()` method, but goes backward from the textiter location.

### Warning

This method is likely to be very slow since the Python function `pred` is called for every character.

### gtk.TextIter.forward_search

        def forward_search(str, flags, limit=None)

`str` : | a search string
`flags` : | the flags affecting how the search is done
`limit` : | a bound for the search, or `None` to set the bound to the end of the buffer
Returns : | a tuple containing `gtk.TextIter` objects pointing at the start and end locations of the match

The `forward_search`() method searches forward for the text string specified by `str` and returns a tuple containing `gtk.TextIter` objects that point at the start and end locations of the match. The search will stop at the location specified by `limit` or the end of the textbuffer if `limit` is `None` or is not specified. Note that a search is a linear or O(n) operation, so you may wish to use `limit` to avoid locking up your UI when searching large buffers.

If the `gtk.TEXT_SEARCH_VISIBLE_ONLY` flag is present, the match may have invisible text interspersed in `str` (i.e. `str` will be a possibly-noncontiguous subsequence of the matched range). Likewise, if `gtk.TEXT_SEARCH_TEXT_ONLY` is present, the match may have pixbufs or child anchors mixed inside the matched range. If these flags are not given, the match must be exact i.e. the special 0xFFFC character in `str` will match embedded pixbufs or child widgets.

### gtk.TextIter.backward_search

        def backward_search(str, flags, limit=None)

`str` : | a search string
`flags` : | the flags affecting the search
`limit` : | a bound for the search, or `None` to set the bound to the end of the buffer
Returns : | start of match and end of match

The `backward_search`() method is the same as the `forward_search`() method, except searches backward.

### gtk.TextIter.equal

        def equal(rhs)

`rhs` : | another `gtk.TextIter` object
Returns : | `TRUE` if the textiters point to the same place in the buffer

The `equal`() method tests if the textiter specified by `rhs` points to the same location in the textbuffer as the textiter.

### gtk.TextIter.compare

        def compare(rhs)

`rhs` : | another `gtk.TextIter` object
Returns : | -1 if the textiter location is less than the `rhs` location, 1 if the textiter location is greater, 0 if they are equal

The `compare`() method returns:

- -1 if the textiter location is less than the location of the textiter specified by `rhs`;
- 1 if the textiter location is greater than the location of the textiter specified by `rhs`; and,
- 0 if the textiter location is equal to the location of the textiter specified by `rhs`.

Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in the buffer.

### gtk.TextIter.in_range

        def in_range(start, end)

`start` : | the start of the text range
`end` : | the end of the text range
Returns : | `TRUE` if the textiter location is in the text range

The `in_range`() method returns `TRUE` if the textiter location is in the text range specified by the `gtk.TextIter` objects `start` and `end`. `start` and `end` must be in ascending order.

### gtk.TextIter.order

        def order(second)

`second` : | another `gtk.TextIter` object

The order() method swaps the locations of `first` and `second` if `second` comes before `first` in the buffer. This method can be used to ensure that `first` and `second` are in sequence. Most text buffer methods that take a range call this automatically, so there's no real reason to call it yourself in those cases. There are some exceptions, such as the `in_range`(), that expect a pre-sorted range.

Prev | Up | Next
gtk.TextChildAnchor | Home | gtk.TextMark