<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:e="http://projectmallard.org/experimental/" type="guide" style="task" id="model-view-controller.py" xml:lang="cs">

<info>

    <title type="text">Návrh typu Model/Zobrazení/Ovládání (Python)</title>

  <link type="guide" xref="beginner.py#theory"/>

  <link type="next" xref="combobox_multicolumn.py"/>

  <revision version="0.1" date="2012-06-30" status="stub"/>

  <desc>Návrh typu Model/Zobrazení/Ovládání</desc>

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

</info>

<title>Návrh typu Model/Zobrazení/Ovládání</title>

<links type="section"/>

<section id="overview">

<title>Přehled</title>

Widgety <link xref="treeview_simple_liststore.py">TreeView</link> i <link xref="combobox.py">ComboBox</link> jsou postaveny na návrhu Model/Zobrazení/Ovládání. Model (implementace Gtk.TreeModel, obvykle Gtk.TreeStore nebo Gtk.ListStore) uchovává data, Zobrazení (např. Gtk.TreeView, Gtk.ComboBox nebo Gtk.ComboBoxText) přijímá upozornění a zobrazuje obsah modelu. A konečně Ovládání mění stav modelu (přes některé metody, které model implementuje, jako je append() nebo remove()) a upozorňuje zobrazení na tyto změny (pomocí signálu, jako je "changed").

</section>

<section id="model">

<title>Model</title>

Hlavní rozdíl mezi dvěma hlavními implementacemi Gtk.TreeModel je, že Gtk.ListStore obsahuje jednoduché řádky dat bez potomků, zatímco Gtk.TreeStore obsahuje sice také řádky dat, ale každý řádek může mít synovské řádky (a ty také mohou mít synovské řádky a tak dále).

Data v modelu mohou být získána nebo změněna pomocí stromového iterátoru a sloupcového indexu nebo metody Gtk.TreeIter nebo Gtk.TreePath.

Stejně jako u objektů typu seznam vestavěných v jazyce Python, můžete použít len() k získání počtu řádků a „slice“ (řez) k získání nebo nastavení hodnot. Jinak metoda append() vrací instanci Gtk.TreeIter, která ukazuje na místo, kam byl nový řádek vložen. Gtk.TreeIter můžete získat i zavoláním get_iter().

Protože Gtk.ListStore obsahuje jen jednu úroveň, tj. uzly nemají žádné potomky, je cesta v podstatě jen index řádku, ke kterému chcete přístup. V případě Gtk.TreeStore je cesta seznam indexů nebo řetězec. Forma řetězce je seznam čísel oddělených dvojtečkami. Každé číslo odkazuje na pořadí v dané úrovni. Takže cesta "0" odkazuje na kořenový uzel a cesta "2:4" odkazuje na pátého potomka třetího uzlu.

Užitečné metody pro Gtk.TreeModel:

<list>

  <item>
get_iter(cesta) vrací instanci Gtk.TreeIter ukazující na cestu. Ta je očekávána v podobě seznamu čísel oddělovaného dvojtečkou nebo n-tice. Například řetězec "10:4:0" je stejná cesta jako n-tice (10, 4, 0), protože obojí vytvoří cestu do hloubky 3. úrovně k 11. potomku od kořene, 5. pátému potomku jedenáctého potomka a 1. potomku pátého potomka.
</item>

  <item>
iter_next(stromový_iterátor) vrací instanci Gtk.TreeIter ukazující na uzel následující za stromovým_iterátorem v aktuální úrovni nebo None, pokud tam již další není.
</item>

  <item>
iter_has_child(stromový_iterátor) vrací True jestliže má stromový_iterátor potomky, jinak False.
</item>

  <item>
iter_children(stromový_iterátor) vrací instanci Gtk.TreeIter ukazující na prvního potomka stromového_iterátoru nebo None, když žádného potomka nemá.
</item>

  <item>
get_iter_first() vrací instanci Gtk.TreeIter, která ukazuje na první iterátor ve stromu (tj. na cestě "0") nebo None, pokud je strom prázdný.
</item>

</list>

Užitečné metody pro Gtk.ListStore:

<list>

  <item>
append(řádek) připojí nový řádek do ListStore, kde řádek může být seznam hodnot pro každý ze sloupců nebo může být řádek vynechán či None a pak bude připojen prázdný řádek. Tato metoda vrací Gtk.TreeIter ukazující na připojený řádek.
</item>

  <item>
remove(iterátor) odstraní iterátor z Gtk.ListStore a vrátí True jestliže je iterátor platný nebo False jestliže není. Po odstranění je iterátor nastaven na následující platný řádek.
</item>

</list>

Užitečné metody pro Gtk.TreeStore:

<list>

  <item>
append(rodič, řádek) přidá do stromového úložiště nový řádek. Argument rodič musí být platný Gtk.TreeIter. Když rodič není None, bude nový řádek přidán za posledního potomka rodiče, jinak bude přidán do nejvyšší úrovně. Argument řádek může být seznam hodnot pro jednotlivé sloupce nebo může být vynechán nebo None. V posledních dvou zmíněných případech bude připojen prázdný řádek. Metoda vrací Gtk.TreeIter ukazující na připojený řádek.
</item>

  <item>
remove(iterátor) odstraní iterátor z Gtk.ListStore a vrátí True jestliže je iterátor platný nebo False jestliže není. Po odstranění je iterátor nastaven na následující platný řádek.
</item>

</list>

</section>

<section id="treeview">

<title>Zobrazení: případ TreeView</title>

TreeView zobrazuje strukturu dceřiných a rodičovských položek v podobě stromu. Viz třeba <link xref="treeview_treestore.py">tento příklad</link>.

Gtk.TreeViewColumn je použito k uspořádání svislých sloupců.

Užitečné metody pro Gtk.TreeView:

<list>

  <item>
set_model(model) nastaví model pro toto stromové zobrazení. Pokud již nějaký model nastavené má, tak ten bude nejdříve odebrán. Jestliže je model None, tak se zruší nastavení starého modelu.
</item>

  <item>
get_model() vrací model, na kterém je strom založen, None, když model není nastaven.
</item>

  <item>
append_column(sloupec) připojí sloupec do seznamu sloupců.
</item>

  <item>
get_selection() vrací Gtk.TreeSelection přidružené k tomuto stromovému zobrazení.
</item>

</list>

Užitečné metody pro Gtk.TreeViewColumn:

<list>

  <item>
add_attribute(vykreslovač, atribut, hodnota) přidá mapování atributu na tento sloupec. atribut je parametr vykreslovače, který má být nastaven na hodnotu.
</item>

  <item>
pack_start(vykreslovač, roztáhnout) zabalí vykreslovač do začátku tohoto sloupce. Když je roztáhnout nastaveno na False, nebude si vykreslovač nárokovat víc místa, než potřebuje. Veškeré nevyužité místo je rovnoměrně rozděleno mezi buňky, kterém mají tento parametr nastavený na True.
</item>

  <item>
pack_end(vykreslovač, roztáhnout) zabalí vykreslovač do konce tohoto sloupce. Když je roztáhnout nastaveno na False, nebude si vykreslovač nárokovat víc místa, než potřebuje. Veškeré nevyužité místo je rovnoměrně rozděleno mezi buňky, kterém mají tento parametr nastavený na True.
</item>

  <item>
set_sort_column_id(id_slupce_řazení) nastaví sloupec z modelu, podle kterého by se měl tento sloupec (v zobrazení) řadit. Rovněž to zpřístupní záhlaví sloupce pro kliknutí.
</item>

  <item>
set_sort_indicator(nastavení) nastaví, jestli se má v záhlaví sloupce zobrazovat malá šipka. Argument nastavení může být True (indikátor je zobrazen) nebo False.
</item>

  <item>
set_sort_order(pořadí) změní pořadí, ve kterém je sloupec seřazen. pořadí může být Gtk.SortType.ASCENDING (vzestupné) nebo Gtk.SortType.DESCENDING (sestupné).
</item>

</list>

</section>

<section id="combobox">

<title>Zobrazení: případ ComboBox</title>

Gtk.ComboBox poskytuje výběr z položek v rozbalovací nabídce, viz třeba <link xref="combobox.py">tento příklad</link>. Pro seznam s čistě textovými položkami lze použít také jednodušší Gtk.ComboBoxText. Obě verze mohou obsahovat vstupní pole.

Užitečné metody pro Gtk.ComboBox:

<list>

  <item>
Statická metoda new_with_entry() vytvoří nový prázdný Gtk.ComboBox se vstupním polem. Statická metoda new_with_model(model) jej vytvoří s modelem inicializovaným na model. A statická metodat new_with_model_and_entry(model) je kombinací dvou předchozích.
</item>

  <item>
get_active_iter() vrací Gtk.TreeIter ukazující na právě aktivní položku. Pokud žádná aktivní položka neexistuje, je vráceno None.
</item>

  <item>
set_model(model) nastaví model použitý tímto rozbalovacím seznamem na model a zruší nastavení předchozího nastaveného modelu (pokud nějaký byl). Pokud je model None, bude jen zrušeno nastavení předchozího. Upozorňujeme, že tato funkce nemaže vykreslovače buněk.
</item>

  <item>
set_entry_text_column(textový_sloupec) nastavuje sloupec modelu, který by měl tento rozbalovací seznam použít k získávání řetězců, na textový_sloupec. Tento sloupec musí být typu str (to platí v případě, že rozbalovací seznam byl vytvořen s vlastností "has-entry" nastavenou na True).
</item>

  <item>
set_wrap_width(šířka) nastavuje šířku zalamování rozbalovacího seznamu na šířka. Jedná se v zásadě o upřednostňovaný počet sloupců, když chcete, aby byl rozbalený seznam rozvržen do mřížky.
</item>

</list>

Užitečné metody pro Gtk.ComboBoxText:

<list>

  <item>
Statická metoda new_with_entry() vytvoří nový prázdný Gtk.ComboBoxText se vstupním polem.
</item>

  <item>
append_text(text) připojí text do seznamu řetězců uchovaných v tomto rozbalovacím seznamu.
</item>

  <item>
get_active_text() vrací aktuálně aktivní řetězec v rozbalovacím seznamu nebo None, když není nic vybráno. V případě, kdy má rozbalovací seznam vstupní pole, vrací tato funkce obsah tohoto pole (což nutně nemusí být žádná položka ze seznamu).
</item>

</list>

</section>

<section id="cellrenderer">

<title>Zobrazení: vykreslování buněk</title>

K vykreslení různých typů dat používá View objekty Gtk.CellRenderer.

Implementace Gtk.CellRenderer a užitečných metod:

<list>

  <item>
Gtk.CellRendererText – vykresluje text v buňce.
</item>

  <item>
Gtk.CellRendererToggle – vykresluje v buňce přepínací tlačítko nebo skupinový přepínač. Užitečné metody:

    <list>

    <item>
set_active(nastavení) – aktivuje nebo deaktivuje vykreslování buňky
</item>

    <item>
get_active() – vrací, jestli je vykreslování buňky aktivní
</item>

    <item>
set_radio(skupinový_přepínač) – pokud je skupinový_přepínač True, bude vykreslovač buňky vykreslovat skupinový přepínač (tj. navzájem se vylučující přepínače), pokud je False, bude se vykreslovat zaškrtávací políčko (samostatná volba)
</item>

    <item>
get_radio() – vrací, jestli vykreslujeme skupinové přepínače místo zaškrtávacích políček.
</item>

    </list>

  </item>

  <item>
Gtk.CellRendererPixbuf – vykresluje obrázek v buňce
</item>

  <item>
Gtk.CellRendererCombo  – vykresluje v buňce text; ale zatímco Gtk.CellRendererText poskytuje jednoduché vstupní pole pro úpravu textu, Gtk.CellRendererCombo poskytuje pro úpravu textu widget Gtk.ComboBox. Ten lze použít s nebo bez přidruženého widgetu Gtk.Entry, v závislosti na vlastnosti "has-entry".
</item>

  <item>
Gtk.CellRendererProgress – vykresluje v buňce číselnou hodnotu v podobě ukazatele průběhu; nad ukazatelem může zobrazit text
</item>

  <item>
Gtk.CellRendererSpinner – vykresluje v buňce animovanou káču
</item>

  <item>
Gtk.CellRendererSpin – vykresluje v buňce číselník
</item>

  <item>
Gtk.CellRendererAccel – vykresluje v buňce klávesovou zkratku
</item>

</list>

</section>

<section id="selection">

<title>Ovládání: výběr</title>

Většina aplikací potřebuje používat nejen zobrazení dat, ale i přijímat vstupní události od uživatelů. To udělají jednoduše tak, že získají odkaz na objekt s výběrem a napojí se na signál "changed".

select = tree.get_selection()

select.connect("changed", on_tree_selection_changed)

Pak k získání dat pro vybraný řádek:

def on_tree_selection_changed(selection):

    model, treeiter = selection.get_selected()

    if treeiter != None:

        print "You selected", model[treeiter][0]

Užitečné metody pro Gtk.TreeSelection:

<list>

  <item>
set_mode(typ) nastaví typ výběru, kde typ může být něco z

  <list>

    <item>
Gtk.SelectionMode.NONE – není možný žádný výběr
</item>

    <item>
Gtk.SelectionMode.SINGLE – může být vybrán žádný nebo jeden prvek
</item>

    <item>
Gtk.SelectionMode.BROWSE – je vybrán právě jeden prvek. V některých případech, jako na počátku nebo v průběhu vyhledávání, je možné, aby nebyl vybrán žádný prvek. To, co je opravdu vynucováno, je, že uživatel nemůže zrušit výběr aktuálně vybraného prvku, jedině může vybrat jiný.
</item>

    <item>
Gtk.SelectionMode.MULTIPLE – může být vybrán libovolný počet prvků. Kliknutí přepne stav položky. Klávesu <key>Ctrl</key> lze používat k přidávání výběru a klávesu <key>Shift</key> k výběru rozsahu mezi zaměřenou a kliknutou položkou. Některé widgety mohou umožňovat výběr rozsahu prvků i postupem „klikni a táhni“.
</item>

  </list>

  </item>

  <item>
get_selected() vrací dvojici (model, stromový_iterátor), kde model je aktuální model a stromový_iterátor je Gtk.TreeIter ukazující na aktuálně vybraný řádek nebo None, když není žádný řádek vybrán. Metoda nepracuje, když je režim výběru nastaven na Gtk.SelectionMode.MULTIPLE. V tomto případě použijte místo toho get_selected_rows(), která vrací seznam instancí Gtk.TreePath se všemi vybranými řádky.
</item>

</list>

</section>

<section id="references">

<title>Odkazy</title>

<list>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeModel.html">GtkTreeModel</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeView.html">GtkTreeView</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeViewColumn.html">GtkTreeViewColumn</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkComboBox.html">GtkComboBox</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkCellRenderer.html">GtkCellRenderer</link>
</item>

</list>

</section>

</page>