<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="textview.py" xml:lang="ca">

  <info>

    <title type="text">TextView (Python)</title>

    <link type="guide" xref="beginner.py#multiline"/>

    <link type="seealso" xref="strings.py"/>

    <link type="seealso" xref="scrolledwindow.py"/>

    <link type="next" xref="dialog.py"/>

    <revision version="0.2" date="2012-06-19" status="draft"/>

    <credit type="author copyright">

      <name>Sebastian Pölsterl</name>

      <email its:translate="no">sebp@k-d-w.org</email>

      <years>2011</years>

    </credit>

    <credit type="author copyright editor">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2012</years>

    </credit>

    <desc>Widget that displays a GtkTextBuffer</desc>

  </info>

  <title>TextView</title>

  <note style="sidebar">
This is an example of Gtk.TextView.

  
If we press "enter", we have a new line.

  
But we can also have a new line if we write a long sentence (the text will wrap breaking lines between words).

  
If we have a loooooooooooooooooooooooooooooooooooong

  
(that was long)

  
word, an horizontal scrollbar will appear.
</note>

  <media type="image" mime="image/png" src="media/textview.png"/>

  <links type="section"/>

  <section id="code">

  <title>Code used to generate this example</title>

  from gi.repository import Gtk

import sys

class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):

        Gtk.Window.__init__(self, title="TextView Example", application=app)

        self.set_default_size(300, 450)

        # a scrollbar for the child widget (that is going to be the textview)

        scrolled_window = Gtk.ScrolledWindow()

        scrolled_window.set_border_width(5)

        # we scroll only if needed

        scrolled_window.set_policy(

            Gtk.PolicyType.AUTOMATIC, Gtk.PolicyType.AUTOMATIC)

        # a text buffer (stores text)

        buffer1 = Gtk.TextBuffer()

        # a textview (displays the buffer)

        textview = Gtk.TextView(buffer=buffer1)

        # wrap the text, if needed, breaking lines in between words

        textview.set_wrap_mode(Gtk.WrapMode.WORD)

        # textview is scrolled

        scrolled_window.add(textview)

        self.add(scrolled_window)

class MyApplication(Gtk.Application):

    def __init__(self):

        Gtk.Application.__init__(self)

    def do_activate(self):

        win = MyWindow(self)

        win.show_all()

    def do_startup(self):

        Gtk.Application.do_startup(self)

app = MyApplication()

exit_status = app.run(sys.argv)

sys.exit(exit_status)

  </section>

  <section id="methods">

  <title>Useful methods for a TextView widget</title>

  
A Gtk.TextView displays the text stored in a Gtk.TextBuffer. However, most text manipulation is accomplished with iterators, represented by a Gtk.TextIter - 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, we use a Gtk.TextMark, that can be set visible with visible(True). A text buffer contains two built-in marks; an "insert" mark (the position of the cursor) and the "selection_bound" mark.

  
Methods for a TextView widget:

  <list>

    <item>
The TextView widget is by default editable. If you prefer otherwise, use set_editable(False). If the buffer has no editable text, it might be a good idea to use set_cursor_visible(False) as well.
</item>

    <item>
The justification of the text is set with set_justification(Gtk.Justification.JUSTIFICATION) where JUSTIFICATION is one of LEFT, RIGHT, CENTER, FILL.
</item>

    <item>
The line wrapping of the text is set with set_wrap_mode(Gtk.WrapMode.WRAP) where WRAP is one of NONE (the text area is made wider), CHAR (break lines anywhere the cursor can appear), WORD (break lines between words), WORD_CHAR (break lines between words, but if that is not enough between characters).
</item>

  </list>

  
Methods for a TextBuffer widget:

  <list>

    <item>
get_insert() returns the Gtk.TextMark that represents the cursor, that is the insertion point.
</item>

    <item>
get_selection_bound() returns the Gtk.TextMark that represents the selection bound.
</item>

    <item>
set_text("some text", length) where length is a positive integer or -1, sets the content of the buffer as the first length characters of the "some text" text. If length is omitted or -1, the text is inserted completely. The content of the buffer, if there is any, is destroyed.
</item>

    <item>
insert(iter, "some text", length) where iter is a text iterator and length is a positive integer or -1, inserts in the buffer at iter the first length characters of the "some text" text. If length is omitted or -1, the text is inserted completely.
</item>

    <item>
insert_at_cursor("some text", length) does the same as insert(iter, "some text", length), with the current cursor taken as iter.
</item>

    <item>
create_mark("mark_name", iter, left_gravity) where iter is a Gtk.TextIter and left_gravity is a boolean, creates a Gtk.TextMark at the position of iter. If "mark_name" is None, the mark is anonymous; otherwise, the mark can be retrieved by name using get_mark(). If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If left_gravity is omitted, it defaults to False.

</item>

    <item>
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 create_tag("tag name", property) and apply_tag(tag, start_iter, end_iter) as in, for instance:

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:

      <list>

        <item>
Background colour ("background" property)
</item>

        <item>
Foreground colour ("foreground" property)
</item>

        <item>
Underline ("underline" property)
</item>

        <item>
Bold ("weight" property)
</item>

        <item>
Italics ("style" property)
</item>

        <item>
Strikethrough ("strikethrough" property)
</item>

        <item>
Justification ("justification" property)
</item>

        <item>
Size ("size" and "size-points" properties)
</item>

        <item>
Text wrapping ("wrap-mode" property)
</item>

      </list>

    
You can also delete particular tags later using remove_tag() or delete all tags in a given region by calling remove_all_tags().
</item>

  </list>

  
Methods for a TextIter widget

  <list>

    <item>
forward_search(needle, flags, limit) searches forward for needle. The search will not continue past the Gtk.TextIter limit. The flags can be set to one of the following, or any combination of it by concatenating them with the bitwise-OR operator |: 0 (the match must be exact); Gtk.TextSearchFlags.VISIBLE_ONLY (the match may have invisible text interspersed in needle); Gtk.TextSearchFlags.TEXT_ONLY (the match may have pixbufs or child widgets mixed inside the matched range); Gtk.TextSearchFlags.CASE_INSENSITIVE (the text will be matched regardless of what case it is in). The method returns a tuple containing a Gtk.TextIter pointing to the start and to the first character after the match; if no match is found, None is returned.
</item>

    <item>
backward_search(needle, flags, limit) does the same as forward_search(), but moving backwards.
</item>

  </list>

  </section>

  <section id="references">

  <title>API References</title>

  
In this sample we used the following:

  <list>

    <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTextView.html">GtkTextView</link>
</item>

    <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTextBuffer.html">GtkTextBuffer</link>
</item>

    <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTextTag.html">GtkTextTag</link>
</item>

    <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkScrolledWindow.html">GtkScrolledWindow</link>
</item>

    <item>
<link href="http://developer.gnome.org/gtk3/unstable/gtk3-Standard-Enumerations.html">Standard Enumerations</link>
</item>

  </list>

  </section>

</page>