/usr/share/doc/python-gtk2-tutorial/html/sec-TextIters.html is in python-gtk2-tutorial 2.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>13.4. Text Iters</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PyGTK 2.0 Tutorial"><link rel="up" href="ch-TextViewWidget.html" title="Chapter 13. TextView Widget"><link rel="previous" href="sec-TextBuffers.html" title="13.3. Text Buffers"><link rel="next" href="sec-TextMarks.html" title="13.5. Text Marks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">13.4. Text Iters</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-TextBuffers.html">Prev</a> </td><th width="60%" align="center">Chapter 13. TextView Widget</th><td width="20%" align="right"> <a accesskey="n" href="sec-TextMarks.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-TextIters"></a>13.4. Text Iters</h2></div></div><div></div></div><p><tt class="classname">TextIters</tt> represent a position between two
characters in a <tt class="classname">TextBuffer</tt>.
<tt class="classname">TextIters</tt> are usually created by using a
<tt class="classname">TextBuffer</tt> method. <tt class="classname">TextIters</tt>
are invalidated when the number of characters in a
<tt class="classname">TextBuffer</tt> is changed (except for the
<tt class="classname">TextIter</tt> that is used for the insertion or
deletion). Inserting or deleting pixbufs or anchors also counts as a
<tt class="classname">TextIter</tt> invalidating change.</p><p>There are a large number of methods associated with a
<tt class="classname">TextIter</tt> object. They are grouped together in the
following sections by similar function.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3122662"></a>13.4.1. TextIter Attributes</h3></div></div><div></div></div><p>The <tt class="classname">TextBuffer</tt> that contains the
<tt class="classname">TextIter</tt> can be retrieved using the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
buffer = iter.get_buffer()
</pre></td></tr></table><p>The following methods can be used to get the location of the
<tt class="classname">TextIter</tt> in the
<tt class="classname">TextBuffer</tt>:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
offset = iter.get_offset() # returns offset in buffer of iter
line_number = iter.get_line() # returns number of line at iter
line_offset = iter.get_line_offset() # returns iter offset in line
numchars = iter.get_chars_in_line() # returns number of chars in line
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3122704"></a>13.4.2. Text Attributes at a TextIter</h3></div></div><div></div></div><p>The <tt class="classname">PangoLanguage</tt> used at a given iter
location in the <tt class="classname">TextBuffer</tt> is obtained by calling the
method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
language = iter.get_language()
</pre></td></tr></table><p>The more general method used to get the text attributes at a
<tt class="classname">TextIter</tt>'s location is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.get_attributes(<b class="parameter"><tt>values</tt></b>)
</pre></td></tr></table><p>where <i class="parameter"><tt>result</tt></i> indicates whether the given
<i class="parameter"><tt>values</tt></i> (<tt class="classname">TextAttributes</tt> object)
were modified. The given <i class="parameter"><tt>values</tt></i> are obtained by using
the <tt class="classname">TextView</tt> method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
values = textview.get_default_attributes()
</pre></td></tr></table><p>The following attributes are accessible from a
<tt class="classname">TextAttributes</tt> object (not implemented in PyGTK <=
1.99.15):</p><div class="informaltable"><table width="100%" border="1"><colgroup><col><col></colgroup><tbody><tr><td>bg_color</td><td>background color</td></tr><tr><td>fg_color</td><td>foreground color</td></tr><tr><td>bg_stipple</td><td>background stipple bitmap</td></tr><tr><td>fg_stipple</td><td>foreground stipple bitmap</td></tr><tr><td>rise</td><td>offset of text above baseline</td></tr><tr><td>underline</td><td>style of underline</td></tr><tr><td>strikethrough</td><td>whether text is strikethrough</td></tr><tr><td>draw_bg</td><td><tt class="literal">TRUE</tt> if some tags affect the drawing of the background</td></tr><tr><td>justification</td><td>style of justification</td></tr><tr><td>direction</td><td>which direction the text runs</td></tr><tr><td>font</td><td>PangoFontDescription in use</td></tr><tr><td>font_scale</td><td>scale of the font in use</td></tr><tr><td>left_margin</td><td>location of left margin</td></tr><tr><td>right_margin</td><td>location of right margin</td></tr><tr><td>pixels_above_lines</td><td>pixels spacing above a line</td></tr><tr><td>pixels_below_lines</td><td>pixel spacing below a line</td></tr><tr><td>pixels_inside_wrap</td><td>pixel spacing between wrapped lines</td></tr><tr><td>tabs</td><td>PangoTabArray in use</td></tr><tr><td>wrap_mode</td><td>mode of wrap in use</td></tr><tr><td>language</td><td>PangoLanguage in use</td></tr><tr><td>invisible</td><td>whether text is invisible (not implemented in GTK+ 2.0)</td></tr><tr><td>bg_full_height</td><td>whether background is fit to full line height</td></tr><tr><td>editable</td><td>whether the text is editable</td></tr><tr><td>realized</td><td>text is realized</td></tr><tr><td>pad1</td><td> </td></tr><tr><td>pad2</td><td> </td></tr><tr><td>pad3</td><td> </td></tr><tr><td>pad4</td><td> </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123006"></a>13.4.3. Copying a TextIter</h3></div></div><div></div></div><p>A <tt class="classname">TextIter</tt> can be duplicated using the
method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
iter_copy = iter.copy()
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123025"></a>13.4.4. Retrieving Text and Objects</h3></div></div><div></div></div><p>Various amounts of text and <tt class="classname">TextBuffer</tt>
objects can be retrieved from a <tt class="classname">TextBuffer</tt> using the
following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
char = iter.get_char() # returns char or 0 if at end of buffer
text = start.get_slice(<b class="parameter"><tt>end</tt></b>) # returns the text between start and end iters
text = start.get_text(<b class="parameter"><tt>end</tt></b>) # returns the text between start and end iters
pixbuf = iter.get_pixbuf() # returns the pixbuf at the location (or None)
anchor = iter.get_child_anchor() # returns the child anchor (or None)
mark_list = iter.get_marks() # returns a list of marks
tag_list = iter.get_toggled_tags() # returns a list of tags that are toggled on or off
tag_list = iter.get_tags() # returns a prioritized list of tags
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123068"></a>13.4.5. Checking Conditions at a TextIter</h3></div></div><div></div></div><p>Tag conditions at the <tt class="classname">TextIter</tt> location
can be checked using the following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.begins_tag(<b class="parameter"><tt>tag</tt></b>=None) # TRUE if tag is toggled on at iter
result = iter.ends_tag(<b class="parameter"><tt>tag</tt></b>=None) # TRUE if tag is toggled off at iter
result = iter.toggles_tag(<b class="parameter"><tt>tag</tt></b>=None) # TRUE if tag is toggled on or off at iter
result = iter.has_tag(<b class="parameter"><tt>tag</tt></b>) # TRUE if tag is active at iter
</pre></td></tr></table><p>These methods return <tt class="literal">TRUE</tt> if the given
<i class="parameter"><tt>tag</tt></i> satisfies the condition at
<i class="parameter"><tt>iter</tt></i>. If the <i class="parameter"><tt>tag</tt></i> is <tt class="literal">None</tt> for
the first three methods then the result is <tt class="literal">TRUE</tt> if any
tag satisfies the condition at <i class="parameter"><tt>iter</tt></i>.</p><p>The following methods indicate whether the text at the
<tt class="classname">TextIter</tt> location is editable or allows text
insertion:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.editable()
result = iter.can_insert(<b class="parameter"><tt>default_editability</tt></b>)
</pre></td></tr></table><p>The <tt class="methodname">editable</tt>() method indicates whether
the <i class="parameter"><tt>iter</tt></i> is in an editable range of text while the
<tt class="methodname">can_insert</tt>() method indicates whether text can be
inserted at <i class="parameter"><tt>iter</tt></i> considering the default editability
of the <tt class="classname">TextView</tt>, <tt class="classname">TextBuffer</tt>
and applicable tags. The <i class="parameter"><tt>default_editability</tt></i> is
usually determined by calling the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
default_editability = textview.get_editable()
</pre></td></tr></table><p>The equivalence of two <tt class="classname">TextIter</tt>s can be
determined with the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
are_equal = lhs.equal(<b class="parameter"><tt>rhs</tt></b>)
</pre></td></tr></table><p>Two <tt class="classname">TextIter</tt>s can be compared with the
method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = lhs.compare(<b class="parameter"><tt>rhs</tt></b>)
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> will be: -1 if
<i class="parameter"><tt>lhs</tt></i> is less than <i class="parameter"><tt>rhs</tt></i>; 0 if
<i class="parameter"><tt>lhs</tt></i> equals <i class="parameter"><tt>rhs</tt></i>; and, 1 if
<i class="parameter"><tt>lhs</tt></i> is greater than <i class="parameter"><tt>rhs</tt></i>.</p><p>To determine whether a <tt class="classname">TextIter</tt> is
located between two given <tt class="classname">TextIter</tt>s use the
method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.in_range(<b class="parameter"><tt>start</tt></b>, <b class="parameter"><tt>end</tt></b>)
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> is <tt class="literal">TRUE</tt> if
<i class="parameter"><tt>iter</tt></i> is between <i class="parameter"><tt>start</tt></i> and
<i class="parameter"><tt>end</tt></i>. Note: <i class="parameter"><tt>start</tt></i> and
<i class="parameter"><tt>end</tt></i> must be in ascending order. This can be
guaranteed using the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
first.order(<b class="parameter"><tt>second</tt></b>)
</pre></td></tr></table><p>which will reorder the <tt class="classname">TextIter</tt> offsets
so that <i class="parameter"><tt>first</tt></i> is before
<i class="parameter"><tt>second</tt></i>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123315"></a>13.4.6. Checking Location in Text</h3></div></div><div></div></div><p>The location of a <tt class="classname">TextIter</tt> with respect
to the text in a <tt class="classname">TextBuffer</tt> can be determined by the
following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.starts_word()
result = iter.ends_word()
result = iter.inside_word()
result = iter.starts_sentence()
result = iter.ends_sentence()
result = iter.inside_sentence()
result = starts_line()
result = iter.ends_line()
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> returns <tt class="literal">TRUE</tt> if
the <tt class="classname">TextIter</tt> 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
<tt class="classname">TextIter</tt>. Note that a line is a collection of
sentences similar to a paragraph.</p><p>The following methods can be used to determine if a
<tt class="classname">TextIter</tt> is at the start or end of the
<tt class="classname">TextBuffer</tt>:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.is_start()
result = iter.is_end()
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> is <tt class="literal">TRUE</tt> if the
<tt class="classname">TextIter</tt> is at the start or end of the
<tt class="classname">TextBuffer</tt>.</p><p>Since a <tt class="classname">TextBuffer</tt> 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 <tt class="classname">TextIter</tt> could be in a
location which is not a cursor position. The following method indicates
whether a <tt class="classname">TextIter</tt> is at a cursor position:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.is_cursor_position()
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123413"></a>13.4.7. Moving Through Text</h3></div></div><div></div></div><p><tt class="classname">TextIter</tt>s can be moved through a
<tt class="classname">TextBuffer</tt> in various text unit strides. The
definition of the text units is set by the
<tt class="classname">PangoLanguage</tt> in use at the
<tt class="classname">TextIter</tt> location. The basic methods are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.forward_char() # forward by one character
result = iter.backward_char() # backward by one character
result = iter.forward_word_end() # forward to the end of the word
result = iter.backward_word_start() # backward to the start of the word
result = iter.forward_sentence_end() # forward to the end of the sentence
result = iter.backward_sentence_start() # backward to the start of the sentence
result = iter.forward_line() # forward to the start of the next line
result = iter.backward_line() # backward to the start of the previous line
result = iter.forward_to_line_end() # forward to the end of the line
result = iter.forward_cursor_position() # forward by one cursor position
result = iter.backward_cursor_position() # forward by one cursor position
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> is <tt class="literal">TRUE</tt> if the
<tt class="classname">TextIter</tt> was moved and <tt class="literal">FALSE</tt> if
the <tt class="classname">TextIter</tt> is at the start or end of the
<tt class="classname">TextBuffer</tt>.</p><p>All of the above methods (except
<tt class="methodname">forward_to_line_end</tt>()) have corresponding methods
that take a count (that can be positive or negative) to move the
<tt class="classname">TextIter</tt> in multiple text unit strides:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.forward_chars(<b class="parameter"><tt>count</tt></b>)
result = iter.backward_chars(<b class="parameter"><tt>count</tt></b>)
result = iter.forward_word_ends(<b class="parameter"><tt>count</tt></b>)
result = iter.backward_word_starts(<b class="parameter"><tt>count</tt></b>)
result = iter.forward_sentence_ends(<b class="parameter"><tt>count</tt></b>)
result = iter.backward_sentence_starts(<b class="parameter"><tt>count</tt></b>)
result = iter.forward_lines(<b class="parameter"><tt>count</tt></b>)
result = iter.backward_lines(<b class="parameter"><tt>count</tt></b>)
result = iter.forward_cursor_positions(<b class="parameter"><tt>count</tt></b>)
result = iter.backward_cursor_positions(<b class="parameter"><tt>count</tt></b>)
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123547"></a>13.4.8. Moving to a Specific Location</h3></div></div><div></div></div><p>A <tt class="classname">TextIter</tt> can be moved to a specific
location in the <tt class="classname">TextBuffer</tt> using the
following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
iter.set_offset(<b class="parameter"><tt>char_offset</tt></b>) # move to given character offset
iter.set_line(<b class="parameter"><tt>line_number</tt></b>) # move to start of given line
iter.set_line_offset(<b class="parameter"><tt>char_on_line</tt></b>) # move to given character offset in current line
iter.forward_to_end() # move to end of the buffer
</pre></td></tr></table><p>In addition, a <tt class="classname">TextIter</tt> can be moved to
a location where a tag is toggled on or off by using the methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = iter.forward_to_tag_toggle(<b class="parameter"><tt>tag</tt></b>)
result = iter.backward_to_tag_taoggle(<b class="parameter"><tt>tag</tt></b>)
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> is <tt class="literal">TRUE</tt> if the
<tt class="classname">TextIter</tt> was moved to a new location where
<i class="parameter"><tt>tag</tt></i> is toggled. If <i class="parameter"><tt>tag</tt></i> is
<tt class="literal">None</tt> then the <tt class="classname">TextIter</tt> will be
moved to the next location where any tag is toggled.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3123641"></a>13.4.9. Searching in Text</h3></div></div><div></div></div><p>A search for a string in a <tt class="classname">TextBuffer</tt> is
done using the methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
match_start, match_end = iter.forward_search(<b class="parameter"><tt>str</tt></b>, <b class="parameter"><tt>flags</tt></b>, <b class="parameter"><tt>limit</tt></b>=None)
match_start, match_end = iter.backward_search(<b class="parameter"><tt>str</tt></b>, <b class="parameter"><tt>flags</tt></b>, <b class="parameter"><tt>limit</tt></b>=None)
</pre></td></tr></table><p>The <i class="parameter"><tt>return</tt></i> value is a tuple containing
<tt class="classname">TextIter</tt>s that indicate the location of the first
character of the match and the first character after the match.
<i class="parameter"><tt>str</tt></i> is the character string to be located.
<i class="parameter"><tt>flags</tt></i> modifies the conditions of the search;
<i class="parameter"><tt>flag</tt></i> values can be:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
gtk.TEXT_SEARCH_VISIBLE_ONLY # invisible characters are ignored
gtk.TEXT_SEARCH_TEXT_ONLY # pixbufs and child anchors are ignored
</pre></td></tr></table><p><i class="parameter"><tt>limit</tt></i> is an optional
<tt class="classname">TextIter</tt> that bounds the search range.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-TextBuffers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch-TextViewWidget.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-TextMarks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.3. Text Buffers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 13.5. Text Marks</td></tr></table></div></body></html>
|