Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
124 lines (99 sloc) 5.93 KB
Multiline Text Editor
=====================
The :class:`Gtk.TextView` widget can be used to display and edit large amounts
of formatted text. Like the :class:`Gtk.TreeView`, it has a model/view design.
In this case the :class:`Gtk.TextBuffer` is the model which represents the text
being edited. This allows two or more :class:`Gtk.TextView` widgets to share the
same :class:`Gtk.TextBuffer`, and allows those text buffers to be displayed
slightly differently. Or you could maintain several text buffers and choose to
display each one at different times in the same :class:`Gtk.TextView` widget.
The View
--------
The :class:`Gtk.TextView` is the frontend with which the user can add, edit and
delete textual data. They are commonly used to edit multiple lines of text.
When creating a :class:`Gtk.TextView` it contains its own default
:class:`Gtk.TextBuffer`, which you can access via the :meth:`Gtk.TextView.get_buffer`
method.
By default, text can be added, edited and removed from the :class:`Gtk.TextView`.
You can disable this by calling :meth:`Gtk.TextView.set_editable`.
If the text is not editable, you usually want to hide the text cursor with
:meth:`Gtk.TextView.set_cursor_visible` as well. In some cases it may be useful
to set the justification of the text with :meth:`Gtk.TextView.set_justification`.
The text can be displayed at the left edge, (:attr:`Gtk.Justification.LEFT`),
at the right edge (:attr:`Gtk.Justification.RIGHT`), centered
(:attr:`Gtk.Justification.CENTER`), or distributed across the complete
width (:attr:`Gtk.Justification.FILL`).
Another default setting of the :class:`Gtk.TextView` widget is long lines of
text will continue horizontally until a break is entered. To wrap the text and
prevent it going off the edges of the screen call :meth:`Gtk.TextView.set_wrap_mode`.
The Model
---------
The :class:`Gtk.TextBuffer` is the core of the :class:`Gtk.TextView` widget, and
is used to hold whatever text is being displayed in the :class:`Gtk.TextView`.
Setting and retrieving the contents is possible with :meth:`Gtk.TextBuffer.set_text`
and :meth:`Gtk.TextBuffer.get_text`.
However, most text manipulation is accomplished with *iterators*, represented by
a :class:`Gtk.TextIter`. An iterator represents a position between two characters
in the text buffer. Iterators are not valid indefinitely; whenever the buffer is
modified in a way that affects the contents of 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 :class:`Gtk.TextMark`.
A text buffer contains two built-in marks; an "insert" mark (which is the position
of the cursor) and the "selection_bound" mark. Both of them can be retrieved using
:meth:`Gtk.TextBuffer.get_insert` and :meth:`Gtk.TextBuffer.get_selection_bound`,
respectively. By default, the location of a :class:`Gtk.TextMark` is not shown.
This can be changed by calling :meth:`Gtk.TextMark.set_visible`.
Many methods exist to retrieve a :class:`Gtk.TextIter`. For instance,
:meth:`Gtk.TextBuffer.get_start_iter` returns an iterator pointing to the first
position in the text buffer, whereas :meth:`Gtk.TextBuffer.get_end_iter` returns
an iterator pointing past the last valid character. Retrieving the bounds of
the selected text can be achieved by calling
:meth:`Gtk.TextBuffer.get_selection_bounds`.
To insert text at a specific position use :meth:`Gtk.TextBuffer.insert`.
Another useful method is :meth:`Gtk.TextBuffer.insert_at_cursor` which inserts
text wherever the cursor may be currently positioned. To remove portions of
the text buffer use :meth:`Gtk.TextBuffer.delete`.
In addition, :class:`Gtk.TextIter` can be used to locate textual matches in the
buffer using :meth:`Gtk.TextIter.forward_search` and
:meth:`Gtk.TextIter.backward_search`.
The start and end iters are used as the starting point of the search and move
forwards/backwards depending on requirements.
Tags
----
Text in a buffer can be marked with tags. A tag is an attribute that can be
applied to some range of text. For example, a tag might be called "bold" and make
the text inside the tag bold. However, the tag concept is more general than that;
tags don't have to affect appearance. They can instead affect the behaviour of
mouse and key presses, "lock" a range of text so the user can't edit it, or
countless other things. A tag is represented by a :class:`Gtk.TextTag` object.
One :class:`Gtk.TextTag` can be applied to any number of text ranges in any number
of buffers.
Each tag is stored in a :class:`Gtk.TextTagTable`. A tag table defines a set of
tags that can be used together. Each buffer has one tag table associated with it;
only tags from that tag table can be used with the buffer. A single tag table can
be shared between multiple buffers, however.
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 using :meth:`Gtk.TextBuffer.create_tag`
and :meth:`Gtk.TextBuffer.apply_tag`::
tag = textbuffer.create_tag("orange_bg", background="orange")
textbuffer.apply_tag(tag, start_iter, end_iter)
The following are some of the common styles applied to text:
* Background colour ("foreground" property)
* Foreground colour ("background" property)
* Underline ("underline" property)
* Bold ("weight" property)
* Italics ("style" property)
* Strikethrough ("strikethrough" property)
* Justification ("justification" property)
* Size ("size" and "size-points" properties)
* Text wrapping ("wrap-mode" property)
You can also delete particular tags later using :meth:`Gtk.TextBuffer.remove_tag`
or delete all tags in a given region by calling :meth:`Gtk.TextBuffer.remove_all_tags`.
Example
-------
.. image:: ../images/textview_example.png
.. literalinclude:: ../examples/textview_example.py
:linenos:
.. _graphemes: http://developer.gnome.org/pango/stable/pango-Text-Processing.html#pango-get-log-attrs
You can’t perform that action at this time.