TextIters represent a position between two characters in a TextBuffer. TextIters are usually created by using a TextBuffer method. TextIters are invalidated when the number of characters in a TextBuffer is changed (except for the TextIter that is used for the insertion or deletion). Inserting or deleting pixbufs or anchors also counts as a TextIter invalidating change. There are a large number of methods associated with a TextIter object. They are grouped together in the following sections by similar function. The TextBuffer that contains the TextIter can be retrieved using the method:
The following methods can be used to get the location of the TextIter in the TextBuffer:
The PangoLanguage used at a given iter location in the TextBuffer is obtained by calling the method:
The more general method used to get the text attributes at a TextIter's location is:
where result indicates whether the given values (TextAttributes object) were modified. The given values are obtained by using the TextView method:
The following attributes are accessible from a TextAttributes object (not implemented in PyGTK <= 1.99.15):
Various amounts of text and TextBuffer objects can be retrieved from a TextBuffer using the following methods:
Tag conditions at the TextIter location can be checked using the following methods:
These methods return TRUE if the given tag satisfies the condition at iter. If the tag is None for the first three methods then the result is TRUE if any tag satisfies the condition at iter. The following methods indicate whether the text at the TextIter location is editable or allows text insertion:
The editable() method indicates whether the iter is in an editable range of text while the can_insert() method indicates whether text can be inserted at iter considering the default editability of the TextView, TextBuffer and applicable tags. The default_editability is usually determined by calling the method:
The equivalence of two TextIters can be determined with the method:
Two TextIters can be compared with the method:
result will be: -1 if lhs is less than rhs; 0 if lhs equals rhs; and, 1 if lhs is greater than rhs. To determine whether a TextIter is located between two given TextIters use the method:
result is TRUE if iter is between start and end. Note: start and end must be in ascending order. This can be guaranteed using the method:
which will reorder the TextIter offsets so that first is before second. The location of a TextIter with respect to the text in a TextBuffer can be determined by the following methods:
result returns TRUE if the TextIter is at the given text location. These methods are somewhat self-explanatory. The definition of the text components and their boundaries is determined by the language used at the TextIter. Note that a line is a collection of sentences similar to a paragraph. The following methods can be used to determine if a TextIter is at the start or end of the TextBuffer:
result is TRUE if the TextIter is at the start or end of the TextBuffer. Since a TextBuffer may contain multiple characters which are effectively viewed as one cursor position (e.g. carriage return-linefeed combination or letter with an accent mark) it's possible that a TextIter could be in a location which is not a cursor position. The following method indicates whether a TextIter is at a cursor position:
TextIters can be moved through a TextBuffer in various text unit strides. The definition of the text units is set by the PangoLanguage in use at the TextIter location. The basic methods are:
result is TRUE if the TextIter was moved and FALSE if the TextIter is at the start or end of the TextBuffer. All of the above methods (except forward_to_line_end()) have corresponding methods that take a count (that can be positive or negative) to move the TextIter in multiple text unit strides:
A TextIter can be moved to a specific location in the TextBuffer using the following methods:
In addition, a TextIter can be moved to a location where a tag is toggled on or off by using the methods:
result is TRUE if the TextIter was moved to a new location where tag is toggled. If tag is None then the TextIter will be moved to the next location where any tag is toggled. A search for a string in a TextBuffer is done using the methods:
The return value is a tuple containing TextIters that indicate the location of the first character of the match and the first character after the match. str is the character string to be located. flags modifies the conditions of the search; flag values can be:
limit is an optional TextIter that bounds the search range. |