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 character 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, the null character is returned; \0 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.