<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.js" xml:lang="es">

  <info>

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

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

    <link type="seealso" xref="button.js"/>

    <link type="seealso" xref="grid.js"/>

    <link type="seealso" xref="GtkApplicationWindow.js"/>

    <link type="seealso" xref="label.js"/>

    <revision version="0.1" date="2012-06-28" status="draft"/>

    <credit type="author copyright">

      <name>Taryn Fox</name>

      <email its:translate="no">jewelfox@fursona.net</email>

      <years>2012</years>

    </credit>

    <desc>Un editor de texto multilínea</desc>

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

      <mal:name>Daniel Mustieles</mal:name>

      <mal:email>daniel.mustieles@gmail.com</mal:email>

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

    </mal:credit>

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

      <mal:name>Nicolás Satragno</mal:name>

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

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

    </mal:credit>

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

      <mal:name>Jorge González</mal:name>

      <mal:email>jorgegonz@svn.gnome.org</mal:email>

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

    </mal:credit>

  </info>

  <title>TextView</title>

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

  
Un «TextView» es realmente (o al menos generalmente) un conjunto anidado de tres objetos.

  <list>

    <item>
En la parte inferior hay un <link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TextBuffer.html">Búfer de texto</link>. Este almacena el texto.
</item>

    <item>
En el medio está el <link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TextView.html">TextView</link>, que es un widget que le permite ver y editar el texto en el búfer. Cambia su tamaño automáticamente dependiendo de cuánto texto hay.
</item>

    <item>
Dado que el cambio de tamaño automático puede hacer un «TextView» difícil de manejar, normalmente se ubica dentro de una «ScrolledWindow». A pesar de su nombre, no es una ventana real en términos de tener una barra de título y un botón «X»; es un widget en el que pone la aplicación que está haciendo, que actúa como una ventana sobre un pedazo más manejable de un «TextView». Si el texto en el búfer es demasiado grande para entrar, aparecerán barras de desplazamiento.
</item>

  </list>

  
Si quiere cambiar el texto que se muestra en el «TextView», actúe en el búfer de texto, dado que es lo que realmente contiene al texto. Es lo mismo si quiere ver lo que se ha introducido en él. Esta aplicación de ejemplo le permite hablar con un pingüino de fantasía, y verifica el búfer de texto para ver si ha introducido la palabra «fish» en él.

  <note>
Las poblaciones de pingüinos reales están decayendo rápidamente, porque el cambio climático está derritiendo el hielo en el que viven y matando a los peces que comen. Si le interesa jugar a un juego de GNOME algo tonto basado en esta premisa, échele un vistazo a <link href="http://pingus.seul.org/">Pingus</link>.
</note>

    <links type="section"/>

  <section id="imports">

    <title>Bibliotecas que importar</title>

#!/usr/bin/gjs

const Gtk = imports.gi.Gtk;

const Lang = imports.lang;

    
Estas son las bibliotecas que necesita importar para que esta aplicación se ejecute. Recuerde que la línea que le dice a GNOME que está usando Gjs siempre tiene que ir al principio.

    </section>

  <section id="applicationwindow">

    <title>Crear la ventana de la aplicación</title>

const TextViewExample = new Lang.Class ({

    Name: 'TextView Example',

    // Create the application itself

    _init: function () {

        this.application = new Gtk.Application ({

            application_id: 'org.example.jstextview' });

        // Connect 'activate' and 'startup' signals to the callback functions

        this.application.connect('activate', Lang.bind(this, this._onActivate));

        this.application.connect('startup', Lang.bind(this, this._onStartup));

    },

    // Callback function for 'activate' signal presents windows when active

    _onActivate: function () {

        this._window.present ();

    },

    // Callback function for 'startup' signal builds the UI

    _onStartup: function () {

        this._buildUI ();

    },

    
Todo el código de este ejemplo va en la clase «TextViewExample». El código anterior crea una <link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link> para poner los widgets y la ventana.

    // Build the application's UI

    _buildUI: function () {

        // Create the application window

        this._window = new Gtk.ApplicationWindow  ({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            title: "Talk to a Penguin",

            default_height: 400,

            default_width: 440,

            border_width: 20 });

    
La función _buildUI es donde se pone todo el código que crea la interfaz de usuario de la aplicación. El primer paso es crear una <link xref="GtkApplicationWindow.js">Gtk.ApplicationWindow</link> nueva para poner dentro todos los widgets.

  </section>

  <section id="textview">

    <title>Crear el «TextView»</title>

        // Create a label for the penguin to talk to you

        this._penguin = new Gtk.Label ({

            height_request: 180,

            width_request: 400,

            label: "Squaaaak?",

            wrap: true });

    
El primer paso en este ejemplo es crear la <link xref="label.js">Label</link> que el pingüino usará para hablarle. Se configura para que tenga ajuste de línea estableciendo su propiedad «wrap» a «true», pero usaremos un método distinto en el «TextView» propio que permite un control más preciso.

        // Create a textview for you to talk to the penguin

        this.buffer = new Gtk.TextBuffer();

        this._textView = new Gtk.TextView ({

            buffer: this.buffer,

            editable: true,

            wrap_mode: Gtk.WrapMode.WORD });

    
El primer paso es crear un «TextBuffer» para poner dentro las palabras. Después de eso se crea el «TextView», y se le dice que use el «TextBuffer» que se creó como su búfer. También se configura para que sea editable, dado que se quiere poder introducir cosas nuevas dentro.

    
La propiedad «wrap_mode» le permite elegir entre cuatro <link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.WrapMode.html">Modos de ajuste de línea</link> diferentes. «Gtk.WrapMode.CHAR», por ejemplo, salta de línea en el medio de una palabra si sigue escribiendo cuando llega al borde. La mayoría de la gente está probablemente acostumbrada a «Gtk.WrapMode.WORD», que pondrá la palabra que está escribiendo en la línea siguiente automáticamente si es demasiado larga.

        // Create a "scrolled window" to put your textview in so it will scroll

        this._scrolled = new Gtk.ScrolledWindow ({

            hscrollbar_policy: Gtk.PolicyType.AUTOMATIC,

            vscrollbar_policy: Gtk.PolicyType.AUTOMATIC,

            shadow_type: Gtk.ShadowType.ETCHED_IN,

            height_request: 180,

            width_request: 400, });

        // Put the textview into the scrolled window

        this._scrolled.add_with_viewport (this._textView);

    
Aquí se crea una «ScrolledWindow», y se configura para que se desplace automáticamente si se vuelve demasiado grande horizontal o verticalmente. También se le da un borde bonito ETCHED_IN. Después de eso, se pone el «TextView» dentro, y se hace que la «ScrolledWindow» dé un punto de vista sobre él.

    </section>

    <section id="ui">

    <title>Crear el resto de la interfaz de usuario</title>

        // Create a grid to organize them in

        this._grid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER });

        // Put the label and textview in the grid one on top of the other

        this._grid.attach (this._penguin, 0, 0, 1, 1);

        this._grid.attach (this._scrolled, 0, 1, 1, 1);

    
La primera <link xref="grid.js">Rejilla</link> que se crea sólo tiene dentro la etiqueta y la «ScrolledWindow».

        // Create a button to send your message to the penguin

        this._send = new Gtk.Button ({

            halign: Gtk.Align.END,

            margin_top: 20,

            label: "Send" });

        this._send.connect ('clicked', Lang.bind (this, this._chat));

        // Create a grid that will have the other grid on top and the button on bottom

        this._mainGrid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER });

        // Add the other grid and the button to the main grid

        this._mainGrid.attach (this._grid, 0, 0, 1, 1);

        this._mainGrid.attach (this._send, 0, 1, 1, 1);

    
Se crea un <link xref="button.js">Botón</link> para enviar su mensaje al pingüino, y una rejilla nueva que tiene la otra en su parte superior y el botón en la parte inferior. El botón tiene un margen en su parte superior, para que no se aplaste contra la «ScrolledWindow».

        // Attach the main grid to the window

        this._window.add (this._mainGrid);

        // Show the window and all child widgets

        this._window.show_all();

    },

    
Finalmente, se adjunta la rejilla principal a la ventana, después se le dice a la ventana y a todo lo que tiene dentro de ella que se vuelva visible cuando se ejecute la aplicación.

  </section>

  <section id="function">

    <title>Función que maneja la respuesta del pingüino</title>

    _chat: function () {

        // Create a random number to determine what the penguin says

        this.number = Math.floor ((Math.random() * 3) + 1);

        // Did you actually say anything?

        if (this.buffer.text) {

            // Did you mention fish?

            if (this.buffer.text.match (/fish/gi)) {

                // Have the penguin squaak about fish

                if (this.number == 1)

                    this._penguin.set_label ("FISH!");

                else if (this.number == 2)

                    this._penguin.set_label ("Fish fish fish fish. Fish!");

                else

                    this._penguin.set_label ("Fish? Fish fish fish. Fish fish. FISH!");

            }

            // I guess you didn't mention fish

            else {

                // Have the penguin talk about penguinny stuff

                if (this.number == 1)

                    this._penguin.set_label ("SQUAAK!");

                else if (this.number == 2)

                    this._penguin.set_label ("Ork ork ork ork squaak. Squaak squaak! *waves flippers*");

                else

                    this._penguin.set_label ("Ork ork ork ork ork?");

            }

        }

        // Clear the buffer

        this.buffer.text = "";

        // Give focus back to the textview so you don't have to click it again

        this._textView.has_focus = true;

    }

});

    
Aquí se usan algunas funciones básicas de JavaScript para que el pingüino diga algo aleatorio. Sin embargo, a los pingüinos les gusta el pescado, por lo que se quiere que si se menciona «fish», el pingüino responda. Para hacer eso, se usa el método «match» del objeto de cadena de JavaScript sobre <file>this.buffer.text</file>, que devuelve el contenido del búfer de texto.

    
Dado que se quiere limpiar el búfer de texto después de cada vez que pulsa «Send», se configura <file>this.buffer.text</file> para que contenga una cadena vacía justo entonces. Después, se devuelve el foco al «TextView», para poder seguir escribiendo sin tener que pulsar en él antes.

// Run the application

let app = new TextViewExample ();

app.application.run (ARGV);

    
Finalmente, se crea una instancia nueva de la clase «TextViewExample» terminada, y se ejecuta la aplicación.

  </section>

  <section id="complete">

    <title>Código de ejemplo completo</title>

#!/usr/bin/gjs

imports.gi.versions.Gtk = '3.0';

const Gtk = imports.gi.Gtk;

class TextViewExample {

    // Create the application itself

    constructor() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstextview'

        });

        // Connect 'activate' and 'startup' signals to the callback functions

        this.application.connect('activate', this._onActivate.bind(this));

        this.application.connect('startup', this._onStartup.bind(this));

    }

    // Callback function for 'activate' signal presents windows when active

    _onActivate() {

        this._window.present();

    }

    // Callback function for 'startup' signal builds the UI

    _onStartup() {

        this._buildUI();

    }

    // Build the application's UI

    _buildUI() {

        // Create the application window

        this._window = new Gtk.ApplicationWindow  ({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            title: "Talk to a Penguin",

            default_height: 400,

            default_width: 440,

            border_width: 20 });

        // Create a label for the penguin to talk to you

        this._penguin = new Gtk.Label ({

            height_request: 180,

            width_request: 400,

            label: "Squaaaak?",

            wrap: true });

        // Create a textview for you to talk to the penguin

        this.buffer = new Gtk.TextBuffer();

        this._textView = new Gtk.TextView ({

            buffer: this.buffer,

            editable: true,

            wrap_mode: Gtk.WrapMode.WORD });

        // Create a "scrolled window" to put your textview in so it will scroll

        this._scrolled = new Gtk.ScrolledWindow ({

            hscrollbar_policy: Gtk.PolicyType.AUTOMATIC,

            vscrollbar_policy: Gtk.PolicyType.AUTOMATIC,

            shadow_type: Gtk.ShadowType.ETCHED_IN,

            height_request: 180,

            width_request: 400, });

        // Put the textview into the scrolled window

        this._scrolled.add_with_viewport (this._textView);

        // Create a grid to organize them in

        this._grid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER });

        // Put the label and textview in the grid one on top of the other

        this._grid.attach (this._penguin, 0, 0, 1, 1);

        this._grid.attach (this._scrolled, 0, 1, 1, 1);

        // Create a button to send your message to the penguin

        this._send = new Gtk.Button ({

            halign: Gtk.Align.END,

            margin_top: 20,

            label: "Send" });

        this._send.connect ('clicked', this._chat.bind(this));

        // Create a grid that will have the other grid on top and the button on bottom

        this._mainGrid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER });

        // Add the other grid and the button to the main grid

        this._mainGrid.attach (this._grid, 0, 0, 1, 1);

        this._mainGrid.attach (this._send, 0, 1, 1, 1);

        // Attach the main grid to the window

        this._window.add (this._mainGrid);

        // Show the window and all child widgets

        this._window.show_all();

    }

    _chat() {

        // Create a random number to determine what the penguin says

        this.number = Math.floor ((Math.random() * 3) + 1);

        // Did you actually say anything?

        if (this.buffer.text) {

            // Did you mention fish?

            if (this.buffer.text.match (/fish/gi)) {

                // Have the penguin squaak about fish

                if (this.number == 1)

                    this._penguin.set_label ("FISH!");

                else if (this.number == 2)

                    this._penguin.set_label ("Fish fish fish fish. Fish!");

                else

                    this._penguin.set_label ("Fish? Fish fish fish. Fish fish. FISH!");

            }

            // I guess you didn't mention fish

            else {

                // Have the penguin talk about penguinny stuff

                if (this.number == 1)

                    this._penguin.set_label ("SQUAAK!");

                else if (this.number == 2)

                    this._penguin.set_label ("Ork ork ork ork squaak. Squaak squaak! *waves flippers*");

                else

                    this._penguin.set_label ("Ork ork ork ork ork?");

            }

        }

        // Clear the buffer

        this.buffer.text = "";

        // Give focus back to the textview so you don't have to click it again

        this._textView.has_focus = true;

    }

};

// Run the application

let app = new TextViewExample ();

app.application.run (ARGV);

  </section>

  <section id="in-depth">

    <title>Documentación en profundidad</title>

<list>

  <item>
<link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">Gtk.ApplicationWindow</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Button.html">Gtk.Button</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Grid.html">Gtk.Grid</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Label.html">Gtk.Label</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.RadioButton.html">Gtk.RadioButton</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.ScrolledWindow.html">Gtk.ScrolledWindow</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TextBuffer.html">Gtk.TextBuffer</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TextView.html">Gtk.TextView</link>
</item>

</list>

  </section>

</page>