<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 10. TextView</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Programming with gtkmm">
<link rel="up" href="index.html" title="Programming with gtkmm">
<link rel="prev" href="sec-comboboxentry.html" title="ComboBoxEntry">
<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 10. 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" title="Chapter 10. TextView">
<div class="titlepage"><div><div><h2 class="title">
<a name="chapter-textview"></a>Chapter 10. TextView</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul>
<li><span class="sect1"><a href="chapter-textview.html#sec-textview-buffer">The Buffer</a></span></li>
<li><span class="sect1"><a href="sec-widgets-and-childanchors.html">Widgets and ChildAnchors</a></span></li>
<li><span class="sect1"><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="sect1" title="The Buffer">
<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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1TextBuffer.html" target="_top">Reference</a></p>
<div class="sect2" title="Iterators">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-iterators"></a>Iterators</h3></div></div></div>
<p>
</p>
</div>
<div class="sect2" title="Tags and Formatting">
<div class="titlepage"><div><div><h3 class="title">
<a name="textview-formatting"></a>Tags and Formatting</h3></div></div></div>
<div class="sect3" title="Tags">
<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">Glib::RefPtr<Gtk::TextBuffer::Tag> refTagMatch =
Gtk::TextBuffer::Tag::create();
refTagMatch->property_background() = "orange";</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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1TextTag.html" target="_top">Reference</a></p>
</div>
<div class="sect3" title="TagTable">
<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">Glib::RefPtr<Gtk::TextBuffer::TagTable> refTagTable =
Gtk::TextBuffer::TagTable::create();
refTagTable->add(refTagMatch);
//Hopefully a future version of <span class="application">gtkmm</span> will have a set_tag_table() method,
//for use after creation of the buffer.
Glib::RefPtr<Gtk::TextBuffer> refBuffer =
Gtk::TextBuffer::create(refTagTable);</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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1TextTagTable.html" target="_top">Reference</a></p>
</div>
<div class="sect3" title="Applying Tags">
<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">refBuffer->apply_tag(refTagMatch, iterRangeStart, iterRangeStop);</pre>
<p>
Or you could specify the tag when first inserting the text:
refBuffer->insert_with_tag(iter, "Some text", refTagMatch);
</p>
<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="sect2" title="Marks">
<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">Glib::RefPtr<Gtk::TextBuffer::Mark> refMark =
refBuffer->create_mark(iter);</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">select_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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1TextMark.html" target="_top">Reference</a></p>
</div>
<div class="sect2" title="The View">
<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> 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="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1TextView.html" target="_top">Reference</a></p>
<div class="sect3" title="Default formatting">
<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="sect3" title="Scrolling">
<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_iter()</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">ComboBoxEntry </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>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
345aa895e80053137c21f8693106c3a0
>
files
>
36
