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
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="highlight.min.css">
<script src="highlight.min.js"></script><script>
hljs.configure({languages: ['cpp']});
hljs.highlightAll();
</script><title>Chapter 14. TextView</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Programming with gtkmm 4">
<link rel="up" href="index.html" title="Programming with gtkmm 4">
<link rel="prev" href="sec-comboboxentry.html" title="ComboBox with an Entry">
<link rel="next" href="sec-widgets-and-childanchors.html" title="Widgets and ChildAnchors">
</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">Chapter 14. TextView</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-comboboxentry.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="sec-widgets-and-childanchors.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="chapter-textview"></a>Chapter 14. TextView</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul class="toc">
<li><span class="section"><a href="chapter-textview.html#sec-textview-buffer">The Buffer</a></span></li>
<li><span class="section"><a href="sec-widgets-and-childanchors.html">Widgets and ChildAnchors</a></span></li>
<li><span class="section"><a href="sec-textview-examples.html">Examples</a></span></li>
</ul>
</div>
<p>
The <code class="classname">TextView</code> widget can be used to display and edit
large amounts of formatted text. Like the <code class="classname">TreeView</code>, it
has a model/view design. In this case the <code class="classname">TextBuffer</code> is
the model.
</p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-textview-buffer"></a>The Buffer</h2></div></div></div>
<p>
<code class="classname">Gtk::TextBuffer</code> is a model containing the data for the
<code class="classname">Gtk::TextView</code>, like the
<code class="classname">Gtk::TreeModel</code> used by <code class="classname">Gtk::TreeView</code>.
This allows two or more <code class="classname">Gtk::TextView</code>s to share the same
<code class="classname">TextBuffer</code>, and allows those TextBuffers to be displayed
slightly differently. Or you could maintain several
<code class="classname">Gtk::TextBuffer</code>s and choose to display each one at different
times in the same <code class="classname">Gtk::TextView</code> widget.
</p>
<p>
The <code class="classname">TextView</code> creates its own default
<code class="classname">TextBuffer</code>, which you can access via the
<code class="methodname">get_buffer()</code> method.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextBuffer.html" target="_top">Reference</a></p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-iterators"></a>Iterators</h3></div></div></div>
<p>
A <code class="classname">Gtk::TextBuffer::iterator</code> and a <code class="classname">Gtk::TextBuffer::const_iterator</code>
represent a position between two characters in the text buffer. Whenever the buffer
is modified in a way that affects the number of characters in the buffer, all outstanding
iterators become invalid. Because of this, iterators can't be used to preserve positions
across buffer modifications. To preserve a position, use <code class="classname">Gtk::TextBuffer::Mark</code>.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextIter.html" target="_top">Reference</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-formatting"></a>Tags and Formatting</h3></div></div></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="textview-formatting-tags"></a>Tags</h4></div></div></div>
<p>
To specify that some text in the buffer should have specific formatting, you must define a tag to hold that formatting information, and then apply that tag to the region of text. For instance, to define the tag and its properties:
</p>
<pre class="programlisting"><code class="code">auto refTagMatch = Gtk::TextBuffer::Tag::create();
refTagMatch->property_background() = "orange";</code></pre>
<p>
You can specify a name for the <code class="classname">Tag</code> when using the
<code class="methodname">create()</code> method, but it is not necessary.
</p>
<p>
The <code class="classname">Tag</code> class has many other properties.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextTag.html" target="_top">Reference</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="textview-formatting-tagtable"></a>TagTable</h4></div></div></div>
<p>
Each <code class="classname">Gtk::TextBuffer</code> uses a
<code class="classname">Gtk::TextBuffer::TagTable</code>, which contains the
<code class="classname">Tag</code>s for that buffer. 2 or more
<code class="classname">TextBuffer</code>s may share the same
<code class="classname">TagTable</code>. When you create <code class="classname">Tag</code>s
you should add them to the <code class="classname">TagTable</code>. For instance:
</p>
<pre class="programlisting"><code class="code">auto refTagTable = Gtk::TextBuffer::TagTable::create();
refTagTable->add(refTagMatch);
//Hopefully a future version of gtkmm will have a set_tag_table() method,
//for use after creation of the buffer.
auto refBuffer = Gtk::TextBuffer::create(refTagTable);</code></pre>
<p>
You can also use <code class="methodname">get_tag_table()</code> to get, and maybe modify,
the <code class="classname">TextBuffer</code>'s default <code class="classname">TagTable</code>
instead of creating one explicitly.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextTagTable.html" target="_top">Reference</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="textview-formatting-applying-tags"></a>Applying Tags</h4></div></div></div>
<p>
If you have created a <code class="classname">Tag</code> and added it to the
<code class="classname">TagTable</code>, you may apply that tag to part of the
<code class="classname">TextBuffer</code> so that some of the text is displayed with that
formatting. You define the start and end of the range of text by specifying
<code class="classname">Gtk::TextBuffer::iterator</code>s. For instance:
</p>
<pre class="programlisting"><code class="code">refBuffer->apply_tag(refTagMatch, iterRangeStart, iterRangeStop);</code></pre>
<p>
Or you could specify the tag when first inserting the text:
</p>
<pre class="programlisting"><code class="code">refBuffer->insert_with_tag(iter, "Some text", refTagMatch);</code></pre>
<p>
You can apply more than one <code class="classname">Tag</code> to the same text, by
using <code class="methodname">apply_tag()</code> more than once, or by using
<code class="methodname">insert_with_tags()</code>. The <code class="classname">Tag</code>s might
specify different values for the same properties, but you can resolve these
conflicts by using <code class="methodname">Tag::set_priority()</code>.
</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-marks"></a>Marks</h3></div></div></div>
<p>
<code class="classname">TextBuffer</code> iterators are generally invalidated when the
text changes, but you can use a <code class="classname">Gtk::TextBuffer::Mark</code> to
remember a position in these situations. For instance,
</p>
<pre class="programlisting"><code class="code">auto refMark = refBuffer->create_mark(iter);</code></pre>
<p>
You can then use the <code class="methodname">get_iter()</code> method later to create an
iterator for the <code class="classname">Mark</code>'s new position.
</p>
<p>
There are two built-in <code class="classname">Mark</code>s - <code class="literal">insert</code>
and <code class="literal">selection_bound</code>, which you can access with
<code class="classname">TextBuffer</code>'s <code class="methodname">get_insert()</code> and
<code class="methodname">get_selection_bound()</code> methods.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextMark.html" target="_top">Reference</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-view"></a>The View</h3></div></div></div>
<p>
As mentioned above, each <code class="classname">TextView</code> has a
<code class="classname">TextBuffer</code>, and one or more
<code class="classname">TextView</code>s can share the same
<code class="classname">TextBuffer</code>.
</p>
<p>
Like the <code class="classname">TreeView</code>, you should probably put your
<code class="classname">TextView</code> inside a <code class="classname">ScrolledWindow</code>
to allow the user to see and move around the whole text area with
scrollbars.
</p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1TextView.html" target="_top">Reference</a></p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="textview-default-formatting"></a>Default formatting</h4></div></div></div>
<p>
<code class="classname">TextView</code> has various methods which allow you to change
the presentation of the buffer for this particular view. Some of these may be
overridden by the <code class="classname">Gtk::TextTag</code>s in the buffer, if they
specify the same things. For instance, <code class="methodname">set_left_margin()</code>,
<code class="methodname">set_right_margin()</code>, <code class="methodname">set_indent()</code>,
etc.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="textview-scrolling"></a>Scrolling</h4></div></div></div>
<p>
<code class="classname">Gtk::TextView</code> has various
<code class="methodname">scroll_to()</code> methods. These allow you to ensure that a
particular part of the text buffer is visible. For instance, your application's
Find feature might use <code class="methodname">Gtk::TextView::scroll_to()</code> to
show the found text.
</p>
</div>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-comboboxentry.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="sec-widgets-and-childanchors.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">ComboBox with an Entry </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Widgets and ChildAnchors</td>
</tr>
</table>
</div>
</body>
</html>
|
