<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="fr">

  <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>L'élément graphique qui affiche un GtkTextBuffer</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Luc Rebert,</mal:name>

      <mal:email>traduc@rebert.name</mal:email>

      <mal:years>2011</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Alain Lojewski,</mal:name>

      <mal:email>allomervan@gmail.com</mal:email>

      <mal:years>2011-2012</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Luc Pionchon</mal:name>

      <mal:email>pionchon.luc@gmail.com</mal:email>

      <mal:years>2011</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Bruno Brouard</mal:name>

      <mal:email>annoa.b@gmail.com</mal:email>

      <mal:years>2011-12</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Luis Menina</mal:name>

      <mal:email>liberforce@freeside.fr</mal:email>

      <mal:years>2014</mal:years>

    </mal:credit>

  </info>

  <title>TextView</title>

  <note style="sidebar">
Ceci est un exemple de Gtk.TextView.

  
En appuyant sur « Entrée », nous créons une nouvelle ligne.

  
Mais il peut également y avoir un retour à la ligne si nous écrivons une longue phrase (la césure se fait entre deux mots).

  
Si nous avons un loooooooooooooooooooooooooooooooooooong

  
(long comme ça)

  
mot, une barre de défilement horizontale apparaît.
</note>

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

  <links type="section"/>

  <section id="code">

  <title>Code utilisé pour générer cet exemple</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>Méthodes utiles pour un élément graphique TextView</title>

  
Un Gtk.TextView affiche le texte stocké dans le tampon d'un Gtk.TextBuffer. Cependant, la plupart des manipulations de texte se font avec des itérateurs représentés par un Gtk.TextIter - une position entre deux caractères dans le tampon du texte. Les itérateurs ne restent pas valides indéfiniment ; à chaque fois que le tampon se trouve modifié d'une façon qui affecte son contenu, tous les itérateurs en cours deviennent non valides. À cause de cela, les itérateurs ne peuvent pas être utilisés pour préserver les positions en cas de modifications du tampon. Pour préserver une position, nous utilisons donc un marqueur Gtk.TextMark, qui peut être rendu visible avec visible(True). Un tampon de texte contient deux marqueurs intégrés : un marqueur « insert » (la position du curseur) et un marqueur « selection_bound » (limite de sélection).

  
Méthodes pour un élément graphique TextView :

  <list>

    <item>
L'élément graphique TextView est modifiable par défaut. Si vous préférez le contraire, utilisez set_editable(False). Si le tampon ne contient pas de texte modifiable, c'est une bonne idée d'utiliser set_cursor_visible(False) aussi.
</item>

    <item>
La justification du texte est définie par set_justification(Gtk.Justification.JUSTIFICATION) où JUSTIFICATION est l'une des valeurs LEFT, RIGHT, CENTER, FILL.
</item>

    <item>
La césure du texte est définie par set_wrap_mode(Gtk.WrapMode.WRAP) où WRAP est une des valeurs NONE (la zone de texte s'élargit), CHAR (fait la césure n'importe où le curseur peut apparaître), WORD (fait la césure entre deux mots), WORD_CHAR (fait la césure entre deux mots, mais si cela ne suffit pas, la fait entre deux caractères).
</item>

  </list>

  
Méthodes pour un élément graphique TextBuffer :

  <list>

    <item>
La méthode get_insert() retourne le marqueur Gtk.TextMark qui représente le curseur, c'est-à-dire le point d'insertion.
</item>

    <item>
La méthode get_selection_bound() renvoie le marqueur Gtk.TextMark qui représente les limites de la sélection.
</item>

    <item>
La méthode set_text("du texte", longueur) où longueur est un nombre entier positif ou -1 définit le contenu du tampon comme étant les longueur premiers caractères du texte du texte. Si longueur est omis ou égal à -1, tout le texte est inséré. Le contenu du tampon, s'il existe, est détruit.
</item>

    <item>
La méthode insert(iter, "du texte", longueur), où iter est un itérateur et longueur est un nombre entier positif ou -1, insère dans le tampon à l'endroit de iter les longueur premiers caractères du texte du texte. Si longueur est omis ou égal à -1, tout le texte est inséré.
</item>

    <item>
La méthode insert_at_cursor("du texte", longueur) effectue la même action que insert(iter, "du texte", length), avec le curseur actuel comme iter.
</item>

    <item>
La méthode create_mark("nom_marqueur", iter, left_gravity), où iter est un Gtk.TextIter et left_gravity une valeur booléenne, crée un marqueur Gtk.TextMark à l'emplacement de l'iter. Si la valeur de "nom_marqueur" est None, le marqueur est anonyme ; sinon, le marqueur peut être récupéré par son nom avec get_mark(). Si un marqueur possède la propriété left_gravity et que le texte est inséré à son emplacement actuel, alors le marqueur est déplacé à gauche du texte qui vient d'être inséré. Si la valeur left_gravity est omise, alors la valeur False est utilisée par défaut.
</item>

    <item>
Pour indiquer qu'un morceau de texte du tampon doit être formatée spécifiquement, vous devez définir une étiquette contenant cette information de formatage et ensuite l'appliquer à la portion de texte en utilisant create_tag("nom etiquette", propriété) et apply_tag(tag, start_iter, end_iter), par exemple comme ceci :

etiquette = textbuffer.create_tag("fond_orange", background="orange")

textbuffer.apply_tag(etiquette, start_iter, end_iter)

     
Voici quelques styles les plus usuels appliqués à du texte :

      <list>

        <item>
Couleur d'arrière-plan (propriété « background »)
</item>

        <item>
Couleur de premier plan (propriété « foreground »)
</item>

        <item>
Souligné (propriété « underline »)
</item>

        <item>
Gras (propriété « weight »)
</item>

        <item>
Italique (propriété « style »)
</item>

        <item>
Barré (propriété « strikethrough »)
</item>

        <item>
Justifié (propriété « justification »)
</item>

        <item>
Taille (propriétés « size » et « size-points »)
</item>

        <item>
Césure (propriété « wrap-mode »)
</item>

      </list>

    
Vous pouvez aussi supprimer par la suite certaines étiquettes en particulier avec remove_tag(), ou supprimer toutes celles d'une région donnée avec remove_all_tags().
</item>

  </list>

  
Méthodes pour un élément graphique TextIter

  <list>

    <item>
La méthode forward_search(needle, flags, limit) effectue une recherche en avant de needle (cible). La recherche ne s'effectue pas au delà de l'itérateur Gtk.TextIter. Les flags (drapeaux) peuvent être définis comme l'un des éléments suivants, ou comme n'importe quelle combinaison de l'un d'eux, en les concaténant avec l'opérateur binaire OR | : 0 (la correspondance doit être exacte) ; Gtk.TextSearchFlags.VISIBLE_ONLY (la correspondance peut contenir du texte invisible intercalé dans la sélection) ; Gtk.TextSearchFlags.TEXT_ONLY (la correspondance peut contenir des pixbufs ou des éléments graphiques enfants mélangés dans la sélection) ; Gtk.TextSearchFlags.CASE_INSENSITIVE (la correspondance n'est pas sensible à la casse). La méthode renvoie un tuple contenant un Gtk.TextIter qui pointe vers le début et vers le premier caractère après la correspondance ; s'il n'y a pas de correspondance, elle renvoie la valeur None.
</item>

    <item>
La méthode backward_search(needle, flags, limit) effectue les même actions que forward_search(), mais en arrière.
</item>

  </list>

  </section>

  <section id="references">

  <title>Références API</title>

  
Dans cet exemple, les éléments suivants sont utilisés :

  <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>