<?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="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"/>
<p><code>TreeView</code> (stromové zobrazení) je něco jako okno do obsahu úložiště <code>ListStore</code> nebo <code>TreeStore</code>. <code>ListStore</code> je podobný tabulce: „plochý“ dvourozměrný seznam věcí rozdělených do řádků a sloupců. <code>TreeStore</code> se oproti němu může větvit do různých směrů podobně jako strom. V tomto příkladu vytvoříme <code>TreeView</code> zobrazující obsah <code>ListStore</code> 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.</p>
<p><code>TreeView</code> ve skutečnosti není jeden widget, ale obsahuje řadu dalších menších:</p>
<list>
<item><p>Widgety <code>TreeViewColumn</code> (sloupec stromového zobrazení) zobrazují jednotlivé (svislé) sloupce s údaji z <code>ListStore</code>. Každý má záhlaví, které může být zobrazené nad sloupcem, podobně jako na snímku obrazovky.</p></item>
<item><p>Widgety <code>CellRenderer</code> (vykreslovač buňky) jsou „zabaleny“ do jednotlivých <code>TreeViewColumn</code> a obsahují instrukce, jak zobrazovat jednotlivé „buňky“ nebo položky z <code>ListStore</code>. Existuje jich více různých typů, včetně <code>CellRendererText</code> použitého zde a <code>CellRendererPixbuf</code>, který zobrazuje obrázky (pixbuf).</p></item>
</list>
<p>A navíc budeme použít objekt nazvaný <code>TreeIter</code>, což není ani tak widget, jako neviditelný kurzor, který ukazuje na (vodorovný) řádek v <code>ListStore</code>. Kdykoliv například kliknete na jméno v adresáři, vytvoříme <code>TreeIter</code> 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í.</p>
<note><p><code>TreeView</code> 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.</p></note>
<links type="section"/>
<section id="imports">
<title>Importované knihovny</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>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.</p>
</section>
<section id="applicationwindow">
<title>Vytvoření okna aplikace</title>
<code mime="application/javascript">
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 ();
},
</code>
<p>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.</p>
<code mime="application/javascript">
// 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"});
</code>
<p>Funkce <code>_buildUI</code> 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.</p>
</section>
<section id="liststore">
<title>Vytvoření ListStore</title>
<code mime="application/javascript">
// 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]);
</code>
<p>Nejprve vytvořím seznamové úložiště obdobně, jako kterýkoliv jiný widget. Pak zavoláme jeho metodu <code>set_column_types</code> a předáme ji pole datových typů <code>GObject</code>. (Mohli bychom je mít všechny na jednom řádku, ale zde je kvůli snadnějšímu čtení rozdělíme.)</p>
<p>Mezi datové typy GObject, které můžete použít, patří:</p>
<list>
<item><p><file>GObject.TYPE_BOOLEAN</file> – Pravda nebo nepravda</p></item>
<item><p><file>GObject.TYPE_FLOAT</file> – Desetinné číslo (tj. s plovoucí desetinou čárkou, resp. tečkou)</p></item>
<item><p><file>GObject.TYPE_STRING</file> – Řetězec písmen a číslic</p></item>
<item><p><file>gtk.gdk.Pixbuf</file> – Obrázek</p></item>
</list>
<p>V tomto případě vytváříme seznamové úložiště se čtyřmi sloupci, přičemž všechny obsahují řetězcové hodnoty.</p>
<note><p>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.</p></note>
<code mime="application/javascript">
// 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!"}];
</code>
<p>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.</p>
<p>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 <code>TreeView</code> a <code>ListStore</code> 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ž <code>ListStore</code>, podobně jako <code>Label</code> v našem příkladu, nebo třeba klidně druhý <code>TreeView</code>.</p>
<code mime="application/javascript">
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]);
}
</code>
<p>Tato smyčka <code>for</code> vkládá řetězce z našeho adresáře do seznamového úložiště ve správném pořadí. Metodě <code>set</code> ú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.</p>
<p>Metoda <code>append</code> objektu <code>ListStore</code> přidává vodorovný řádek (na začátku je bez řádků) a vrací <code>TreeIter</code> ukazující na tento nový řádek. Takže předáním <code>this._listStore.append()</code> do seznamového úložiště jako vlastnosti vytvoříme nový řádek a zároveň řekneme metodě <code>set</code>, která data má do řádku vložit.</p>
</section>
<section id="treeview">
<title>Vytvoření TreeView</title>
<code mime="application/javascript">
// Vytvoří stromové zobrazení
this._treeView = new Gtk.TreeView ({
expand: true,
model: this._listStore });
</code>
<p>Zde vytvoříme základní widget <code>TreeView</code>, 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 <code>ListStore</code>, který jsme vytvořili jako jeho „model“ neboli věc, ze které se budou věci zobrazovat.</p>
<code mime="application/javascript">
// 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" });
</code>
<p>Nyní vytvoříme jednotlivé svislé sloupce <code>TreeViewColumn</code>, 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.</p>
<code mime="application/javascript">
// 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);
</code>
<p>Zde vytváříme vykreslovače <code>CellRenderer</code>, které použijeme k zobrazení textu z <code>ListStore</code>, a balíme je do příslušných <code>TreeViewColumn</code>. Každý <code>CellRendererText</code> je použit pro všechny záznamy ve sloupci. Náš normální <code>CellRendererText</code> 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ě <code>pack_start</code> je jako druhý parametr použita hodnota <code>true</code>, která říká, že má roztáhnout buňku co nejvíce to jde, místo, aby ji udržovala kompaktní.</p>
<note><p><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 <code>const Pango = imports.gi.Pango;</code> na začátek svého kódu.</p></note>
<code mime="application/javascript">
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);
</code>
<p>Nyní vložíme jednotlivé <code>CellRenderer</code> do příslušných <code>TreeViewColumn</code>. Použijeme metodu <code>add_attribute</code>, 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ě <code>ListStore</code> s adresářem).</p>
<list>
<item><p>První parametr je vykreslovač buňky, který hodláme použít k vykreslení toho, co jsme vytáhli.</p></item>
<item><p>Druhým parametrem je druh informací, které vytahujeme. V tomto případě vězte, že vykreslujeme text.</p></item>
<item><p>Třetím parametrem je číslo sloupce seznamového úložiště, ze kterého se data mají vytahovat.</p></item>
</list>
<p>Po té, co jsme toto nastavili, použijeme metodu <code>insert_column</code> stromového zobrazení k vložení našich sloupců <code>TreeViewColumn</code> do něj ve správném pořadí. Nyní je náš stromový pohled kompletní.</p>
<note><p>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í.</p></note>
</section>
<section id="ui">
<title>Sestavení zbytku uživatelského rozhraní</title>
<code mime="application/javascript">
// 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));
</code>
<p>Metoda <code>get_selection</code> widgetu <code>TreeView</code> vrací objekt nazvaný <code>TreeSelection</code>. Ten je, podobně jako <code>TreeIter</code>, v podstatě kurzor ukazující na konkrétní řádek, vyjma toho, že tento ukazuje na řádek vizuálně zvýrazněný jako vybraný.</p>
<p>Po té, co získáme objekt <code>TreeSelection</code>, 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 <code>"changed"</code> na funkci <code>_onSelectionChanged</code>, kterou jsme napsali. Tato funkce mění text zobrazený v popisku, který jsme právě vytvořili.</p>
<code mime="application/javascript">
// 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();
},
</code>
<p>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.</p>
</section>
<section id="function">
<title>Funkce, která obsluhuje změnu výběru</title>
<code mime="application/javascript">
_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));
}
});
</code>
<p>Řádek s výrazem <code>let</code> je poněkud spletitý, nicméně je to nejlepší způsob, jak získat <code>TreeIter</code> ukazující na stejný řádek jako náš <code>TreeSelection</code>. Vytvoří n-tici dalších odkazů na objekty, ale <code>iter</code> je jediný, který nás zajímá.</p>
<p>Když máme toto hotovo, zavoláme funkci <code>set_label</code> z widgetu <code>Label</code> a použijeme funkci <code>get_value</code> z <code>ListStore</code> 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.</p>
<p>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.</p>
<code mime="application/javascript">
// Spustí aplikaci
let app = new TreeViewExample ();
app.application.run (ARGV);
</code>
<p>Nakonec vytvoříme novou instanci konečné třídy TreeViewExample a aplikaci spustíme.</p>
</section>
<section id="complete">
<title>Úplný kód ukázky</title>
<code mime="application/javascript" style="numbered">#!/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);
</code>
</section>
<section id="in-depth">
<title>Dokumentace jdoucí do hloubky</title>
<p>V této ukázce se používá následující:</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>