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

  <info>

  <title type="text">TreeView s 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>Widget, který zobrazuje samostatný seznam položek</desc>

  </info>

  <title>TreeView s ListStore</title>

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

  
TreeView (stromové zobrazení) je něco jako okno do obsahu úložiště ListStore nebo TreeStore. ListStore je podobný tabulce: „plochý“ dvourozměrný seznam věcí rozdělených do řádků a sloupců. TreeStore se oproti němu může větvit do různých směrů podobně jako strom. V tomto příkladu vytvoříme TreeView zobrazující obsah ListStore se (smyšlenými) jmény a telefonními čísly a k tomu widget <link xref="label.js">Label</link> ve spodní části okna, který bude zobrazovat více informací ke jménu, na které v seznamu kliknete.

  
TreeView ve skutečnosti není jeden widget, ale obsahuje řadu dalších menších:

  <list>

    <item>
Widgety TreeViewColumn (sloupec stromového zobrazení) zobrazují jednotlivé (svislé) sloupce s údaji z ListStore. Každý má záhlaví, které může být zobrazené nad sloupcem, podobně jako na snímku obrazovky.
</item>

    <item>
Widgety CellRenderer (vykreslovač buňky) jsou „zabaleny“ do jednotlivých TreeViewColumn a obsahují instrukce, jak zobrazovat jednotlivé „buňky“ nebo položky z ListStore. Existuje jich více různých typů, včetně CellRendererText použitého zde a CellRendererPixbuf, který zobrazuje obrázky (pixbuf).
</item>

  </list>

  
A navíc budeme použít objekt nazvaný TreeIter, což není ani tak widget, jako neviditelný kurzor, který ukazuje na (vodorovný) řádek v ListStore. Kdykoliv například kliknete na jméno v adresáři, vytvoříme TreeIter ukazující na řádek, který je vybrán a použijeme jej, abychom řekli úložišti, který záznam chceme pro popisek zobrazující o záznamech více informací.

  <note>
TreeView je pravděpodobně nejsložitější widget v Gtk tím, jakou má spoustu částí a jak ty spolupracují. Věnujte chvilku času studiu, jak funguje a experimentujte s ním, nebo, když s ním budete mít problémy, zkuste nejdřív něco jednoduššího.
</note>

    <links type="section"/>

  <section id="imports">

    <title>Importované knihovny</title>

#!/usr/bin/gjs

const GObject = imports.gi.GObject;

const Gtk = imports.gi.Gtk;

const Lang = imports.lang;

const Pango = imports.gi.Pango;

    
Toto jsou knihovny, které potřebujeme naimportovat, aby aplikace běžela. Pamatujte si, že řádek, který GNOME říká, že používáme Gjs, musí být vždy na začátku.

  </section>

  <section id="applicationwindow">

    <title>Vytvoření okna aplikace</title>

const TreeViewExample = new Lang.Class({

    Name: 'TreeView Example with Simple ListStore',

    // Vytvoří vlastní aplikaci

    _init: function() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstreeviewsimpleliststore'

        });

    // Napojí signály "activate" a "startup" k funkcím zpětného volání

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

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

    },

    // Funkce zpětného volání pro signál "activate" zobrazujicí okno při aktivaci

    _onActivate: function() {

        this._window.present();

    },

    // Funkce zpětného volání pro signál "startup" sestavující uživatelské rozhraní

    _onStartup: function() {

        this._buildUI ();

    },

    
Všechen kód této ukázky je ve třídě TreeViewExample. Výše uvedený kód vytvoří <link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link> pro naše widgety a okno, ve kterém budou.

    // Sestaví uživatelské rozhraní aplikace

    _buildUI: function() {

        // Vytvoří okno aplikace

        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"});

    
Funkce _buildUI je místo, ze kterého voláme všechen kód, který vytváří uživatelské rozhraní aplikace. Prvním krokem je vytvoření nového <link xref="GtkApplicationWindow.js">Gtk.ApplicationWindow</link>, do kterého vložíme všechny naše widgety.

  </section>

  <section id="liststore">

    <title>Vytvoření ListStore</title>

        // Vytvoří podkladový ListStore pro telefonní seznam

        this._listStore = new Gtk.ListStore ();

        this._listStore.set_column_types ([

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING]);

    
Nejprve vytvořím seznamové úložiště obdobně, jako kterýkoliv jiný widget. Pak zavoláme jeho metodu set_column_types a předáme ji pole datových typů GObject. (Mohli bychom je mít všechny na jednom řádku, ale zde je kvůli snadnějšímu čtení rozdělíme.)

    
Mezi datové typy GObject, které můžete použít, patří:

    <list>

      <item>
<file>GObject.TYPE_BOOLEAN</file> – Pravda nebo nepravda
</item>

      <item>
<file>GObject.TYPE_FLOAT</file> – Desetinné číslo (tj. s plovoucí desetinou čárkou, resp. tečkou)
</item>

      <item>
<file>GObject.TYPE_STRING</file> – Řetězec písmen a číslic
</item>

      <item>
<file>gtk.gdk.Pixbuf</file> – Obrázek
</item>

    </list>

    
V tomto případě vytváříme seznamové úložiště se čtyřmi sloupci, přičemž všechny obsahují řetězcové hodnoty.

    <note>
Abyste mohli používat typy GObject, potřebujete vložit řádek <file>const GObject = imports.gi.GObject;</file> na začátek kódu aplikace tak, jako jsem učinili v tomto příkladu.
</note>

        // Data do telefonního seznamu

        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!"}];

    
Zde máme údaje, které přijdou do seznamového úložiště. Jedná se o pole objektů, kdy každý odpovídá jednomu záznamu v adresáři.

    
Všimněte si, že stromové zobrazení na snímku obrazovky ve skutečnosti nezobrazuje data z vlastnosti „description“. Místo toho je tato vlastnost zobrazena v popisku pod ním a to pro řádek, na který jste klikli. To je proto, že TreeView a ListStore jsou dvě oddělené věci, a stromové zobrazení může zobrazovat všechny nebo jen některé sloupce ze seznamového úložiště a může je zobrazovat různými způsoby. Na druhou stranu můžete mít více widgetů, které budou zobrazovat věci z téhož ListStore, podobně jako Label v našem příkladu, nebo třeba klidně druhý TreeView.

        for (i = 0; i < 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]);

        }

    
Tato smyčka for vkládá řetězce z našeho adresáře do seznamového úložiště ve správném pořadí. Metodě set úložiště předáváme iterátor ukazující na správný řádek, pole říkající, které sloupce chceme nastavit, a pole obsahující data, která chceme do těchto sloupců vložit.

    
Metoda append objektu ListStore přidává vodorovný řádek (na začátku je bez řádků) a vrací TreeIter ukazující na tento nový řádek. Takže předáním this._listStore.append() do seznamového úložiště jako vlastnosti vytvoříme nový řádek a zároveň řekneme metodě set, která data má do řádku vložit.

  </section>

  <section id="treeview">

    <title>Vytvoření TreeView</title>

        // Vytvoří stromové zobrazení

        this._treeView = new Gtk.TreeView ({

            expand: true,

            model: this._listStore });

    
Zde vytvoříme základní widget TreeView, který se roztáhne ve vodorovném i svislém směru, aby zabral co nejvíce místa může. Nastavíme, aby používal ListStore, který jsme vytvořili jako jeho „model“ neboli věc, ze které se budou věci zobrazovat.

        // Vytvoří sloupce pro telefonní seznam

        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });

        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });

        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });

    
Nyní vytvoříme jednotlivé svislé sloupce TreeViewColumn, které ve stromovém zobrazení vidíme. Názvy jednotlivých sloupců se objeví v záhlaví, jak můžete vidět na snímku obrazovky.

        // Vytvoří vykreslovač buňky pro potřeby tučného textu

        let bold = new Gtk.CellRendererText ({

            weight: Pango.Weight.BOLD });

        // Vytvoří vykreslovač buňky pro normální text

        let normal = new Gtk.CellRendererText ();

        // Zabalí vykreslovače buněk ke sloupcům

        firstName.pack_start (bold, true);

        lastName.pack_start (normal, true);

        phone.pack_start (normal, true);

    
Zde vytváříme vykreslovače CellRenderer, které použijeme k zobrazení textu z ListStore, a balíme je do příslušných TreeViewColumn. Každý CellRendererText je použit pro všechny záznamy ve sloupci. Náš normální CellRendererText jen vytvoří prostý text, zatímco ten pro tučný text použije text se změněnou vlastností weight. Ten vložíme do prvního sloupce a ostatním dvoum řekneme, aby používali kopie toho normálního. V metodě pack_start je jako druhý parametr použita hodnota true, která říká, že má roztáhnout buňku co nejvíce to jde, místo, aby ji udržovala kompaktní.

    <note>
<link href="http://www.pygtk.org/docs/pygtk/pango-constants.html">Zde je seznam</link> dalších vlastností textu, které můžete použít. Abyste mohli tyto konstanty používat, musíte vložit řádek const Pango = imports.gi.Pango; na začátek svého kódu.
</note>

        firstName.add_attribute (bold, "text", 0);

        lastName.add_attribute (normal, "text", 1);

        phone.add_attribute (normal, "text", 2);

        // Vloží sloupce do treeview

        this._treeView.insert_column (firstName, 0);

        this._treeView.insert_column (lastName, 1);

        this._treeView.insert_column (phone, 2);

    
Nyní vložíme jednotlivé CellRenderer do příslušných TreeViewColumn. Použijeme metodu add_attribute, která jednotlivým sloupcům říká, aby si vytáhli text z modelu našeho stromového zobrazení, které se používá (v tomto případě ListStore s adresářem).

    <list>

      <item>
První parametr je vykreslovač buňky, který hodláme použít k vykreslení toho, co jsme vytáhli.
</item>

      <item>
Druhým parametrem je druh informací, které vytahujeme. V tomto případě vězte, že vykreslujeme text.
</item>

      <item>
Třetím parametrem je číslo sloupce seznamového úložiště, ze kterého se data mají vytahovat.
</item>

    </list>

    
Po té, co jsme toto nastavili, použijeme metodu insert_column stromového zobrazení k vložení našich sloupců TreeViewColumn do něj ve správném pořadí. Nyní je náš stromový pohled kompletní.

    <note>
Normálně byste asi chtěli použít k inicializaci svého stromového pohledu smyčku, ale v tomto příkladu to provedeme krok za krokem v zájmu snazšího pochopení.
</note>

  </section>

  <section id="ui">

    <title>Sestavení zbytku uživatelského rozhraní</title>

        // Vytvoří popisek, který zobrazuje podrobnosti ke jménu, které jste vybrali

        this._label = new Gtk.Label ({ label: "" });

        // Vrátí, která položka je vybrána

        this.selection = this._treeView.get_selection();

        // Když je vybráno něco nového, zavolá _on_changed

        this.selection.connect ('changed', Lang.bind (this, this._onSelectionChanged));

    
Metoda get_selection widgetu TreeView vrací objekt nazvaný TreeSelection. Ten je, podobně jako TreeIter, v podstatě kurzor ukazující na konkrétní řádek, vyjma toho, že tento ukazuje na řádek vizuálně zvýrazněný jako vybraný.

    
Po té, co získáme objekt TreeSelection, které patří našemu stromovému zobrazení, řekneme mu, aby nám sděloval změny v řádku, na který ukazuje. Uděláme to napojením jeho signálu "changed" na funkci _onSelectionChanged, kterou jsme napsali. Tato funkce mění text zobrazený v popisku, který jsme právě vytvořili.

        // Vytvoří mřížku, do které vše uspořádáme

        this._grid = new Gtk.Grid;

        // Připojí stromové zobrazení a popisek do mřížky

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

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

        // Přidá mřížku do okna

        this._window.add (this._grid);

        // Zobrazí okno a všechny jeho synovské widgety

        this._window.show_all();

    },

    
Po té, co jsem tohle vyřešili, vytvoříme <link xref="grid.js">Grid</link>, do které vše vložíme, a pak ji přidáme do našeho okna a oknu řekneme, aby zobrazilo sebe i svůj obsah.

  </section>

  <section id="function">

    <title>Funkce, která obsluhuje změnu výběru</title>

    _onSelectionChanged: function () {

        // Získá iteraci stromového zobrazení ukazující na aktuální výběr

        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Nastaví popisek, aby vytáhl údaje uchované v aktuálním výběru

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

    }

});

    
Řádek s výrazem let je poněkud spletitý, nicméně je to nejlepší způsob, jak získat TreeIter ukazující na stejný řádek jako náš TreeSelection. Vytvoří n-tici dalších odkazů na objekty, ale iter je jediný, který nás zajímá.

    
Když máme toto hotovo, zavoláme funkci set_label z widgetu Label a použijeme funkci get_value z ListStore patřičně krát k vyplnění dat, která chceme do popisku vložit. Jejím parametrem jsou stromový iterátor, který ukazuje na řádek, ze kterého data chceme, a sloupec.

    
Zde chceme získat data ze čtyř sloupců, včetně jednoho „skrytého“, který není součástí stromového zobrazení. Tímto způsobem můžeme použít náš popisek, aby zobrazil řetězce, které jsou příliš dlouhé na to, aby byly vidět ve stromovém zobrazení, a ty, které nepotřebujeme v přehledu vidět.

// Spustí aplikaci

let app = new TreeViewExample ();

app.application.run (ARGV);

    
Nakonec vytvoříme novou instanci konečné třídy TreeViewExample a aplikaci spustíme.

  </section>

  <section id="complete">

    <title>Úplný kód ukázky</title>

#!/usr/bin/gjs

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

const GObject = imports.gi.GObject;

const Gtk = imports.gi.Gtk;

const Pango = imports.gi.Pango;

class TreeViewExample {

    // Vytvoří vlastní aplikaci

    constructor() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstreeviewsimpleliststore'

        });

    // Napojí signály "activate" a "startup" k funkcím zpětného volání

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

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

    }

    // Funkce zpětného volání pro signál "activate" zobrazujicí okno při aktivaci

    _onActivate() {

        this._window.present();

    }

    // Funkce zpětného volání pro signál "startup" sestavující uživatelské rozhraní

    _onStartup() {

        this._buildUI();

    }

    // Sestaví uživatelské rozhraní aplikace

    _buildUI() {

        // Vytvoří okno aplikace

        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"});

        // Vytvoří podkladový ListStore pro telefonní seznam

        this._listStore = new Gtk.ListStore ();

        this._listStore.set_column_types ([

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING]);

        // Data do telefonního seznamu

        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!"}];

        // Vloží data do telefonního seznamu

        for (let i = 0; i < 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]);

        }

        // Vytvoří stromové zobrazení

        this._treeView = new Gtk.TreeView ({

            expand: true,

            model: this._listStore });

        // Vytvoří sloupce pro telefonní seznam

        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });

        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });

        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });

        // Vytvoří vykreslovač buňky pro potřeby tučného textu

        let bold = new Gtk.CellRendererText ({

            weight: Pango.Weight.BOLD });

        // Vytvoří vykreslovač buňky pro normální text

        let normal = new Gtk.CellRendererText ();

        // Zabalí vykreslovače buněk ke sloupcům

        firstName.pack_start (bold, true);

        lastName.pack_start (normal, true);

        phone.pack_start (normal, true);

        // Nastaví u každého sloupce, aby tahal text z modelu TreeView

        firstName.add_attribute (bold, "text", 0);

        lastName.add_attribute (normal, "text", 1);

        phone.add_attribute (normal, "text", 2);

        // Vloží sloupce do treeview

        this._treeView.insert_column (firstName, 0);

        this._treeView.insert_column (lastName, 1);

        this._treeView.insert_column (phone, 2);

        // Vytvoří popisek, který zobrazuje podrobnosti ke jménu, které jste vybrali

        this._label = new Gtk.Label ({ label: "" });

        // Vrátí, která položka je vybrána

        this.selection = this._treeView.get_selection();

        // Když je vybráno něco nového, zavolá _on_changed

        this.selection.connect ('changed', this._onSelectionChanged.bind(this));

        // Vytvoří mřížku, do které vše uspořádáme

        this._grid = new Gtk.Grid;

        // Připojí stromové zobrazení a popisek do mřížky

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

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

        // Přidá mřížku do okna

        this._window.add (this._grid);

        // Zobrazí okno a všechny jeho synovské widgety

        this._window.show_all();

    }

    _onSelectionChanged() {

        // Získá iteraci stromového zobrazení ukazující na aktuální výběr

        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Nastaví popisek, aby vytáhl údaje uchované v aktuálním výběru

        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)

        );

    }

};

// Spustí aplikaci

let app = new TreeViewExample ();

app.application.run (ARGV);

  </section>

  <section id="in-depth">

    <title>Dokumentace jdoucí do hloubky</title>

V této ukázce se používá následující:

<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.CellRendererText.html">Gtk.CellRendererText</link>
</item>

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

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

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

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

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

</list>

  </section>

</page>