<?xml version="1.0" encoding="utf-8"?>
<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="treeview_simple_liststore.js" xml:lang="es">
  <info>
  <title type="text">TreeView con ListStore (JavaScript)</title>
    <link type="guide" xref="beginner.js#treeview"/>
    <link type="seealso" xref="GtkApplicationWindow.js"/>
    <link type="seealso" xref="grid.js"/>
    <link type="seealso" xref="label.js"/>
    <revision version="0.1" date="2012-07-04" status="draft"/>

    <credit type="author copyright">
      <name>Taryn Fox</name>
      <email its:translate="no">jewelfox@fursona.net</email>
      <years>2012</years>
    </credit>

    <desc>Un widget que muestra una lista separada de elementos</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 - 2014</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>TreeView con ListStore</title>
  <media type="image" mime="image/png" src="media/treeview_simple_liststore_penguins.png"/>
  <p>Un TreeView es como una ventana sobre los contenidos de un ListStore o un TreeStore. Un ListStore es como una hoja de cálculo: una lista de cosas «plana», de dos dimensiones, dividida en filas y columnas. Un TreeStore, en cambio, puede bifurcarse en distintas direcciones como un árbol. En este ejemplo, se crea un TreeView que muestra el contenido de un ListStore con nombres y números de teléfono (ficticios), y se configura para que la <link xref="label.js">Etiqueta</link> en la parte inferior de la ventana muestre más información acerca de cualquier nombre en el que pulse.</p>
  <p>Un TreeView no es solamente un widget individual, sino que contiene varios más pequeños.</p>
  <list>
    <item><p>Los widgets TreeViewColumn muestran cada columna (vertical) de información del ListStore. Cada uno tiene un título que puede mostrarse en la parte superior de la columna, como en la captura de pantalla.</p></item>
    <item><p>Los widgets CellRenderer se «empaquetan» en cada TreeViewColumn, y contienen las instrucciones de cómo mostrar cada «celda» individual, o elemento del ListStore. Hay varios tipos diferentes, incluyendo el CellRendererText que se usa aquí y el CellRendererPixbuf, que muestra una imagen («búfer de píxeles»).</p></item>
  </list>
  <p>Finalmente, se usará un objeto llamado TreeIter, que no es un widget sino un cursor invisible que apunta a una fila (horizontal) en el ListStore. Cada vez que pulsa en un nombre en la libreta de direcciones, por ejemplo, se crea un TreeIter apuntando a la fila seleccionada, y después se usa para decirle al ListStore el elemento del que tiene que mostrar más información.</p>
  <note><p>El TreeView es probablemente el widget de GTK más complicado, por la cantidad de partes que tiene y por cómo tienen que trabajar juntas. Tómese un tiempo para aprender cómo funciona y experimentar con él, o intente algo más fácil primero si encuentra problemas.</p></note>
    <links type="section"/>

  <section id="imports">
    <title>Bibliotecas que importar</title>
    <code mime="application/javascript">
#!/usr/bin/gjs

const GObject = imports.gi.GObject;
const Gtk = imports.gi.Gtk;
const Lang = imports.lang;
const Pango = imports.gi.Pango;
</code>
    <p>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.</p>
  </section>

  <section id="applicationwindow">
    <title>Crear la ventana de la aplicación</title>
    <code mime="application/javascript">
const TreeViewExample = new Lang.Class({
    Name: 'TreeView Example with Simple ListStore',

    // Create the application itself
    _init: function() {
        this.application = new Gtk.Application({
            application_id: 'org.example.jstreeviewsimpleliststore'
        });

    // 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 window when active
    _onActivate: function() {
        this._window.present();
    },

    // Callback function for 'startup' signal builds the UI
    _onStartup: function() {
        this._buildUI ();
    },
</code>
    <p>Todo el código de este ejemplo va en la clase TreeViewExample. 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> en la que van los widgets y la ventana.</p>
    <code mime="application/javascript">
    // Build the application's UI
    _buildUI: function() {

        // Create the application window
        this._window = new Gtk.ApplicationWindow({
            application: this.application,
            window_position: Gtk.WindowPosition.CENTER,
            default_height: 250,
            default_width: 100,
            border_width: 20,
            title: "My Phone Book"});
</code>
    <p>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.</p>
  </section>

  <section id="liststore">
    <title>Crear el ListStore</title>
    <code mime="application/javascript">
        // Create the underlying liststore for the phonebook
        this._listStore = new Gtk.ListStore ();
        this._listStore.set_column_types ([
            GObject.TYPE_STRING,
            GObject.TYPE_STRING,
            GObject.TYPE_STRING,
            GObject.TYPE_STRING]);
</code>
    <p>Primero se crea el ListStore como cualquier otro widget. Después se llama a su método set_column_types, y se le pasa una matriz de tipos de datos GObject (se podrían haber puesto todos los tipos en una sola línea, pero aquí se separan para hacerlo más fácil de leer).</p>
    <p>Los tipos de datos GObject que puede usar incluyen:</p>
    <list>
      <item><p><file>GObject.TYPE_BOOLEAN</file>: verdadero o falso</p></item>
      <item><p><file>GObject.TYPE_FLOAT</file>: un número de coma flotante (uno con coma decimal)</p></item>
      <item><p><file>GObject.TYPE_STRING</file>: una cadena de letras y números</p></item>
      <item><p><file>gtk.gdk.Pixbuf</file>: una imagen</p></item>
    </list>
    <p>En este caso, se está haciendo un ListStore de cuatro columnas, cada una conteniendo valores de cadenas.</p>
    <note><p>Necesita poner la línea <file>const GObject = imports.gi.GObject;</file> al principio del código de su aplicación, como se hizo en este ejemplo, si quiere poder usar tipos de GObject.</p></note>

    <code mime="application/javascript">
        // Data to go in the phonebook
        this.phonebook =
        let phonebook =
            [{ name: "Jurg", surname: "Billeter", phone: "555-0123",
                description: "A friendly person."},
             { name: "Johannes", surname: "Schmid", phone: "555-1234",
                description: "Easy phone number to remember."},
             { name: "Julita", surname: "Inca", phone: "555-2345",
                description: "Another friendly person."},
             { name: "Javier", surname: "Jardon", phone: "555-3456",
                description: "Bring fish for his penguins."},
             { name: "Jason", surname: "Clinton", phone: "555-4567",
                description: "His cake's not a lie."},
             { name: "Random J.", surname: "Hacker", phone: "555-5678",
                description: "Very random!"}];
</code>
    <p>Aquí se tiene la información que va en el ListStore. Es una matriz de objetos, cada uno correspondiente a una única entrada en la libreta de direcciones.</p>
    <p>Tenga en cuenta que el TreeView en la captura de pantalla no muestra en realidad los datos de las propiedades «description». En su lugar, esa información se muestra en la etiqueta debajo, para cada fila en la que pulse. Eso es así porque el TreeView y el ListStore son dos cosas separadas, y un TreeView puede mostrar todo o parte de un ListStore, y mostrar su información de maneras diferentes. Puede hacer que varios widgets muestren cosas del mismo ListStore, como la etiqueta del ejemplo, o incluso un segundo TreeView.</p>

    <code mime="application/javascript">
        for (i = 0; i &lt; phonebook.length; i++ ) {
            let contact = phonebook [i];
            this._listStore.set (this._listStore.append(), [0, 1, 2, 3],
                [contact.name, contact.surname, contact.phone, contact.description]);
        }
</code>
    <p>Este bucle <file>for</file> pone las cadenas de la libreta de direcciones en el ListStore ordenadas. En orden, se le pasa al método «set» del ListStore el iter que apunta a la fila correcta, una matriz que dice qué columnas se quieren establecer, y una matriz que contiene los datos que se quieren poner en esas columnas.</p>
    <p>Un método <file>append</file> del ListStore le añade una fila horizontal (empieza sin ninguna), y devuelve un TreeIter apuntando a esa fila como un cursor. Entonces, pasándole <file>this._listStore.append()</file> al ListStore como una propiedad, se está creando una fila nueva y diciéndole al método <file>set</file> en qué fila tiene que establecer los datos al mismo tiempo.</p>

  </section>

  <section id="treeview">
    <title>Crear el TreeView</title>
    <code mime="application/javascript">
        // Create the treeview
        this._treeView = new Gtk.TreeView ({
            expand: true,
            model: this._listStore });
</code>
    <p>Aquí se crea un widget TreeView básico, que se expande tanto horizontal como verticalmente para usar tanto espacio como se necesite. Se configura para usar el ListStore que se creó como su «modelo», o aquello desde donde mostrará datos.</p>

    <code mime="application/javascript">
        // Create the columns for the address book
        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });
        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });
        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });
</code>
    <p>Ahora se crean todas las TreeViewColumns verticales que se verán en el TreeView. El título de cada una va en la parte superior, como puede ver en la captura de pantalla.</p>

    <code mime="application/javascript">
        // Create a cell renderer for when bold text is needed
        let bold = new Gtk.CellRendererText ({
            weight: Pango.Weight.BOLD });

        // Create a cell renderer for normal text
        let normal = new Gtk.CellRendererText ();

        // Pack the cell renderers into the columns
        firstName.pack_start (bold, true);
        lastName.pack_start (normal, true);
        phone.pack_start (normal, true);
</code>
    <p>Aquí se crean los CellRenderer que se usarán para mostrar el texto del ListStore, y se empaquetan en las TreeViewColumn. Cada CellRendererText se usa para todas las entradas en esa columna. El CellRendererText normal sólo crea texto plano, mientras que el «bold» usa texto en negrita. Se pone en la primera columna de nombre, y se le dice a las otras dos que usen copias de la normal. El «true» usado como segundo parámetro para el método <file>pack_start</file> le dice que expanda las celdas cuando sea posible, en lugar de mantenerlas compactas.</p>
    <note><p><link href="http://www.pygtk.org/docs/pygtk/pango-constants.html">Aquí hay una lista</link> de otras propiedades de texto que puede usar. Para usar estas constantes de Pango, asegúrese de poner la línea <file>const Pango = imports.gi.Pango;</file> al principio del código como se hizo.</p></note>

    <code mime="application/javascript">
        firstName.add_attribute (bold, "text", 0);
        lastName.add_attribute (normal, "text", 1);
        phone.add_attribute (normal, "text", 2);

        // Insert the columns into the treeview
        this._treeView.insert_column (firstName, 0);
        this._treeView.insert_column (lastName, 1);
        this._treeView.insert_column (phone, 2);
</code>
    <p>Ahora que se han puesto los CellRenderer en las TreeViewColumn, se usa el método <file>add_attribute</file> para decirle a cada columna que obtenga texto del modelo que el TreeView está configurado para usar; en este caso, el ListStore con la libreta de direcciones.</p>
    <list>
      <item><p>El primer parámetro es qué CellRenderer se usará para procesar lo que se está obteniendo.</p></item>
      <item><p>El segundo parámetro es qué tipo de información se obtendrá. En este caso, se le está haciendo saber que se procesa texto.</p></item>
      <item><p>El tercer parámetro es de cuál de las columnas del ListStore se está obteniendo la información.</p></item>
    </list>
    <p>Después de haber preparado eso, se usa el método <file>insert_column</file> del TreeView para poner dentro las TreeViewColumn en orden. El TreeView ahora está terminado.</p>
    <note><p>Normalmente, usaría un bucle para inicializar su TreeView, pero en este ejemplo se hacen las cosas paso a paso para hacerlo más fácil de entender.</p></note>
  </section>

  <section id="ui">
    <title>Crear el resto de la IU</title>
    <code mime="application/javascript">
        // Create the label that shows details for the name you select
        this._label = new Gtk.Label ({ label: "" });

        // Get which item is selected
        this.selection = this._treeView.get_selection();

        // When something new is selected, call _on_changed
        this.selection.connect ('changed', Lang.bind (this, this._onSelectionChanged));
</code>
    <p>El método <file>get_selection</file> del TreeView devuelve un objeto llamado TreeSelection. Una TreeSelection es como un TreeIter en el sentido de que es básicamente un cursor que apunta a una fila particular, excepto que apunta a la que está resaltada visiblemente como seleccionada.</p>
    <p>Después de obtener la TreeSelection que va con el TreeView, le pedimos que nos diga cuándo cambia la fila a la que está apuntando. Esto se hace conectando la señal <file>changed</file> a la función «_onSelectionChanged» que se escribió. Esta función cambia el texto que muestra la etiqueta que se acaba de hacer.</p>

    <code mime="application/javascript">
        // Create a grid to organize everything in
        this._grid = new Gtk.Grid;

        // Attach the treeview and label to the grid
        this._grid.attach (this._treeView, 0, 0, 1, 1);
        this._grid.attach (this._label, 0, 1, 1, 1);

        // Add the grid to the window
        this._window.add (this._grid);

        // Show the window and all child widgets
        this._window.show_all();
    },
</code>
    <p>Después de haber terminado eso, se crea una <link xref="grid.js">Rejilla</link> para poner todo dentro, se añade a la ventana y se le dice a esta que se muestre y revele su contenido.</p>
  </section>

  <section id="function">
    <title>Función que maneja una selección cambiada</title>

    <code mime="application/javascript">
    _onSelectionChanged: function () {

        // Grab a treeiter pointing to the current selection
        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Set the label to read off the values stored in the current selection
        this._label.set_label ("\n" +
            this._listStore.get_value (iter, 0) + " " +
            this._listStore.get_value (iter, 1) + " " +
            this._listStore.get_value (iter, 2) + "\n" +
            this._listStore.get_value (iter, 3));

    }

});
</code>
    <p>La línea de código con la declaración let es un poco compleja, pero sin embargo es la mejor manera de hacer que un TreeIter apunte a la misma fila que la TreeSelection. Tiene que crear un par de referencias a otros objetos, pero <file>iter</file> es la única que se necesita.</p>
    <p>Después de haber hecho eso, se llama a la función <file>set_label</file> de la etiqueta, y se usa la función <file>get_value</file> del ListStore algunas veces para llenar los datos que queremos poner en ella. Sus parámetros son un TreeIter apuntando a la fila de la que queremos obtener los datos, y la columna.</p>
    <p>Aquí, se quieren obtener datos de todas las cuatro columnas, incluyendo la «escondida» que no es parte del TreeView. De esta manera, se puede usar la etiqueta para mostrar cadenas que son demasiado largas para entrar en el TreeView, y que no necesitamos ver de un vistazo.</p>

    <code mime="application/javascript">
// Run the application
let app = new TreeViewExample ();
app.application.run (ARGV);
</code>
    <p>Finalmente, se crea una instancia nueva de la clase TreeViewExample terminada, y se ejecuta la aplicación.</p>
  </section>

  <section id="complete">
    <title>Código de ejemplo completo</title>
<code mime="application/javascript" style="numbered">#!/usr/bin/gjs

const GObject = imports.gi.GObject;
const Gtk = imports.gi.Gtk;
const Lang = imports.lang;
const Pango = imports.gi.Pango;

const TreeViewExample = new Lang.Class({
    Name: 'TreeView Example with Simple ListStore',

    // Create the application itself
    _init: function() {
        this.application = new Gtk.Application({
            application_id: 'org.example.jstreeviewsimpleliststore'
        });

    // 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 window when active
    _onActivate: function() {
        this._window.present();
    },

    // Callback function for 'startup' signal builds the UI
    _onStartup: function() {
        this._buildUI ();
    },



    // Build the application's UI
    _buildUI: function() {

        // Create the application window
        this._window = new Gtk.ApplicationWindow({
            application: this.application,
            window_position: Gtk.WindowPosition.CENTER,
            default_height: 250,
            default_width: 100,
            border_width: 20,
            title: "My Phone Book"});

        // Create the underlying liststore for the phonebook
        this._listStore = new Gtk.ListStore ();
        this._listStore.set_column_types ([
            GObject.TYPE_STRING,
            GObject.TYPE_STRING,
            GObject.TYPE_STRING,
            GObject.TYPE_STRING]);

        // Data to go in the phonebook
        let phonebook =
            [{ name: "Jurg", surname: "Billeter", phone: "555-0123",
                description: "A friendly person."},
             { name: "Johannes", surname: "Schmid", phone: "555-1234",
                description: "Easy phone number to remember."},
             { name: "Julita", surname: "Inca", phone: "555-2345",
                description: "Another friendly person."},
             { name: "Javier", surname: "Jardon", phone: "555-3456",
                description: "Bring fish for his penguins."},
             { name: "Jason", surname: "Clinton", phone: "555-4567",
                description: "His cake's not a lie."},
             { name: "Random J.", surname: "Hacker", phone: "555-5678",
                description: "Very random!"}];

        // Put the data in the phonebook
        for (let i = 0; i &lt; phonebook.length; i++ ) {
            let contact = phonebook [i];
            this._listStore.set (this._listStore.append(), [0, 1, 2, 3],
                [contact.name, contact.surname, contact.phone, contact.description]);
        }

        // Create the treeview
        this._treeView = new Gtk.TreeView ({
            expand: true,
            model: this._listStore });

        // Create the columns for the address book
        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });
        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });
        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });

        // Create a cell renderer for when bold text is needed
        let bold = new Gtk.CellRendererText ({
            weight: Pango.Weight.BOLD });

        // Create a cell renderer for normal text
        let normal = new Gtk.CellRendererText ();

        // Pack the cell renderers into the columns
        firstName.pack_start (bold, true);
        lastName.pack_start (normal, true);
        phone.pack_start (normal, true);

        // Set each column to pull text from the TreeView's model
        firstName.add_attribute (bold, "text", 0);
        lastName.add_attribute (normal, "text", 1);
        phone.add_attribute (normal, "text", 2);

        // Insert the columns into the treeview
        this._treeView.insert_column (firstName, 0);
        this._treeView.insert_column (lastName, 1);
        this._treeView.insert_column (phone, 2);

        // Create the label that shows details for the name you select
        this._label = new Gtk.Label ({ label: "" });

        // Get which item is selected
        this.selection = this._treeView.get_selection();

        // When something new is selected, call _on_changed
        this.selection.connect ('changed', Lang.bind (this, this._onSelectionChanged));

        // Create a grid to organize everything in
        this._grid = new Gtk.Grid;

        // Attach the treeview and label to the grid
        this._grid.attach (this._treeView, 0, 0, 1, 1);
        this._grid.attach (this._label, 0, 1, 1, 1);

        // Add the grid to the window
        this._window.add (this._grid);

        // Show the window and all child widgets
        this._window.show_all();
    },



    _onSelectionChanged: function () {

        // Grab a treeiter pointing to the current selection
        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Set the label to read off the values stored in the current selection
        this._label.set_label ("\n" +
            this._listStore.get_value (iter, 0) + " " +
            this._listStore.get_value (iter, 1) + " " +
            this._listStore.get_value (iter, 2) + "\n" +
            this._listStore.get_value (iter, 3));

    }

});

// Run the application
let app = new TreeViewExample ();
app.application.run (ARGV);
</code>
  </section>

  <section id="in-depth">
    <title>Documentación en profundidad</title>
<p>En este ejemplo se usa lo siguiente:</p>
<list>
  <item><p><link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link></p></item>
  <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">Gtk.ApplicationWindow</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.CellRendererText.html">Gtk.CellRendererText</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.ListStore.html">Gtk.ListStore</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TreeIter.html">Gtk.TreeIter</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TreeSelection.html">Gtk.TreeSelection</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TreeView.html">Gtk.TreeView</link></p></item>
  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TreeViewColumn.html">Gtk.TreeViewColumn</link></p></item>
</list>
  </section>
</page>