<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="guitar-tuner.vala" xml:lang="cs">

  <info>
    <link type="guide" xref="vala#examples"/>

    <desc>Pomocí <link href="http://developer.gnome.org/platform-overview/stable/gtk">GTK+</link> a <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">GStreamer</link> sestavíme jednoduchou aplikaci GNOME fungující jako kytarová ladička. Ukážeme si také, jak používat návrhář rozhraní.</desc>

    <revision pkgversion="0.1" version="0.1" date="2012-02-09" status="candidate"/>
    <credit type="author">
      <name>Dokumentační projekt GNOME</name>
      <email its:translate="no">gnome-doc-list@gnome.org</email>
    </credit>
    <credit type="author">
      <name>Johannes Schmid</name>
      <email its:translate="no">jhs@gnome.org</email>
    </credit>
    <credit type="editor">
      <name>Tiffany Antopolski</name>
      <email its:translate="no">tiffany.antopolski@gmail.com</email>
    </credit>
  <credit type="editor">
    <name>Marta Maria Casetti</name>
    <email its:translate="no">mmcasetti@gmail.com</email>
    <years>2013</years>
  </credit>
  </info>

<title>Kytarová ladička</title>

<synopsis>
  <p>V této lekci vytvoříte aplikaci, která přehrává tóny, které můžete použít k naladění kytary. Naučíte se:</p>
  <list type="numbered">
    <item><p>Vytvořit základní projekt pomocí <link xref="getting-ready">IDE Anjuta</link>.</p></item>
    <item><p>Vytvořit jednoduché GUI v návrháři uživatelského rozhraní <app>Anjuta</app>.</p></item>
    <item><p>Používat knihovnu <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">GStreamer</link> k přehrávání zvuků.</p></item>
  </list>
  <p>Abyste mohli pokračovat v této lekci, budete potřebovat následující:</p>
  <list>
    <item><p>Základní znalosti programovacího jazyka <link href="https://live.gnome.org/Vala/Tutorial">Vala</link>.</p></item>
    <item><p>Nainstalovanou kopii vývojářského studia <app>Anjuta</app>.</p></item>
  </list>
</synopsis>

<media type="image" mime="image/png" src="media/guitar-tuner.png"/>

<section id="anjuta">
  <title>Vytvoření projektu v IDE <app>Anjuta</app>.</title>
  <p>Než začnete s kódováním, musíte ve studiu Anjuta vytvořit nový projekt. Tím se vytvoří všechny soubory, které budete později potřebovat k sestavení a spuštění kódu. Je to také užitečné kvůli udržení všeho pohromadě.</p>
  <steps>
    <item>
    <p>Spusťte aplikaci <app>Anjuta</app> a klikněte na  <gui>Vytvořit nový projekt</gui> nebo <guiseq><gui>Soubor</gui> <gui>Nový</gui> <gui>Projekt</gui></guiseq>, aby se otevřel průvodce projektem.</p>
    </item>
    <item>
    <p>Na kartě <gui>Vala</gui> zvolte <gui>GTK+ (jednoduchý)</gui>. Klikněte na <gui>Pokračovat</gui> a na několika následujících stránkách vyplňte své údaje. Jako název projektu a složky použijte <file>guitar-tuner</file>.</p>
   	</item>
    <item>
    <p>Ujistěte se, že <gui>Konfigurovat externí balíčky</gui> je přepnuto na <gui>Zapnuto</gui>. Na následující stránce vyberte v seznamu <link href="http://valadoc.org/gstreamer-0.10/index.htm"><em>gstreamer-0.10</em></link>, aby se knihovna GStreamer zahrnula do vašeho projektu. Klikněte na <gui>Pokračovat</gui>.</p>
    </item>
    <item>
    <p>Klikněte na <gui>Použít</gui> a vytvoří se vám projekt. Dvojitým kliknutím na kartě <gui>Projekt</gui> nebo <gui>Soubor</gui> otevřete <file>src/guitar_tuner.vala</file>. Měli byste vidět kód, který začíná řádky:</p>
    <code mime="text/x-csharp">
using GLib;
using Gtk;</code>
    </item>
  </steps>
</section>

<section id="build">
  <title>Prvotní sestavení kódu</title>
  <p>Kód načte (prázdné) okno ze souboru s popisem uživatelského rozhraní a zobrazí jej. Dále to podrobněji rozebereme. Pokud jste již pochopili základy, tak tento seznam můžete přeskočit:</p>

  <list>
  <item>
    <p>Dva řádky <code>using</code> importují jmenné prostory, takže je nebudeme muset výslovně uvádět.</p>
   </item>
   <item>
    <p>Konstruktor třídy <code>Main</code> vytvoří nové okno otevřením souboru GtkBuilder (<file>src/guitar-tuner.ui</file> definovaný a pár řádků dřív), napojí jeho signály a zobrazí jej v okně. Soubor obsahuje popis uživatelského rozhraní a všech jeho prvků. K návrhu uživatelského rozhraní můžete použít editor v IDE Anjuta.</p>
    <note>
    <p>Napojení signálu je způsob, jak definovat, co se má stát, když zmáčknete tlačítko nebo se prostě něco přihodí. Zde je zavolána funkce <code>on_destroy</code> (a ukončení aplikace) při zavření okna.</p>
    </note>
   </item>
   <item>
    <p>Statická funkce <code>main</code> se spustí jako výchozí, když spustíte aplikaci napsanou v jazyce Vala. Volá pár funkcí, které vytvoří třídu <code>Main</code> a nastaví a spustí aplikaci. Funkce <code>Gtk.main</code> spustí hlavní smyčku GTK, která spustí uživatelské rozhraní a začne naslouchat událostem (jako je kliknutí nebo zmáčknutí klávesy).</p>
   </item>
  </list>

  <p>Kód je připraven k použití, takže jej můžete zkompilovat kliknutím na <guiseq><gui>Sestavit</gui> <gui>Sestavit projekt</gui></guiseq> (nebo zmáčknutím <keyseq><key>Shift</key> <key>F7</key></keyseq>). Když to uděláte, objeví se dialogové okno. Změňte <gui>Konfiguraci</gui> na <gui>Výchozí</gui> a klikněte na <gui>Spustit</gui>, aby se nakonfigurovala složka, ve které se provádí sestavení. Stačí to udělat jen jednou, pro první sestavení.</p>
</section>

<section id="ui">
  <title>Vytvoření uživatelského rozhraní</title>
  <p>Popis uživatelského rozhraní se nachází v souboru GtkBuilder <file>src/guitar_tuner.ui</file> definovaném na začátku třídy. Když chcete uživatelské rozhraní upravit, otevřete <file>src/guitar_tuner.ui</file> dvojitým kliknutím na něj v části <gui>Projekt</gui> nebo <gui>Soubory</gui>. Přepnete se tím do návrháře rozhraní. Navrhované okno je uprostřed, widgety a jejich vlastnosti jsou napravo a paleta dostupných widgetů je nalevo.</p>
  <p>Rozvržení každého uživatelského rozhraní v GTK+ je provedeno pomocí boxů a mřížek. Zde použijeme svislý <code>GtkButtonBox</code>, do kterého přiřadíme šest <code>GtkButtons</code>, jedno pro každou z kytarových strun.</p>

<media type="image" mime="image/png" src="media/guitar-tuner-glade.png"/>

  <steps>
   <item>
   <p>Kliknutím na ikonu vyberte <gui>Box na tlačítka</gui> (GtkButtonBox) z oddílu <gui>Kontejnery</gui> na kartě <gui>Paleta</gui>. Pak kliknutím na návrh okna uprostřed tento box do okna umístěte. Objeví se dialogové okno, kde nastavte <gui>Počet položek</gui> na <input>6</input>. Nakonec klikněte na <gui>Vytvořit</gui>.</p>
 <note><p>Můžete také změnit <gui>Počet prvků</gui> a <gui>Orientaci</gui> na kartě <gui>Obecné</gui> napravo.</p></note>
   </item>
   <item>
    <p>Nyní na <gui>Paletě</gui> v oddílu <gui>Ovládání a zobrazení</gui> vyberte kliknutím <gui>Tlačítko</gui> (GtkButton). Umístěte jej do první části GtkButtonBox kliknutím do této první části.</p>
   </item>
   <item>
    <p>Zatímco je tlačítko stále vybráno, přejděte napravo na kartu <gui>Obecné</gui> na vlastnost <gui>Popisek</gui>a změňte ji na <gui>E</gui>. Bude se jednat o spodní kytarovou strunu E.</p>
  <note><p>Karta <gui>Obecné</gui> se nachází v části <gui>Widgety</gui> napravo.</p></note>
    </item>
    <item>
     <p>Přepněte se na kartu <gui>Signál</gui> v části <gui>Widgety</gui> napravo a podívejte se po signálu <code>clicked</code> tlačítka. Můžete jej použít k napojení na obsluhu signálu, která bude volána, když uživatel na tlačítko klikne. Provede se to kliknutím na signál a vepsáním <code>main_on_button_clicked</code> do sloupce <gui>Obslužná rutina</gui> a zmáčknutím <key>Enter</key>.</p>
    </item>
    <item>
    <p>Zopakujte předchozí kroky pro ostatní tlačítka, takže přidáte následujících 5 strun s názvy <em>A</em>, <em>D</em>, <em>G</em>, <em>B</em> a <em>e</em>.</p>
    </item>
    <item>
    <p>Návrh uživatelského rozhraní uložte (kliknutím na <guiseq><gui>Soubor</gui> <gui>Uložit</gui></guiseq>) a ponechte jej otevřený.</p>
    </item>
  </steps>
</section>

<section id="gstreamer">
  <title>Roury systému GStreamer</title>
  <p>Tato část předvádí, jak vytvořit kód, který vydává zvuk. <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">GStreamer</link> je základní multimediální rámec GNOME. Můžete jej použít k přehrávání, nahrávání a zpracování videa, zvuku, vysílání z webové kamery a podobně. Zde jej použijeme ke generování tónu s jednou frekvencí.</p>
  <p>Koncepčně GStreamer funguje následovně: Vytvoříte <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-bins.html"><em>rouru</em></link> obsahující různé prvky zpracující směrem od <em>zdroje</em> do <em>cíle</em> (výstupu). Zdrojem může být například soubor s obrázkem, videosoubor nebo hudební soubor, výstupem pak widget nebo zvuková karta.</p>
  <p>Na cestě mezi zdrojem a cílem můžete použít různé filtry a převodníky k vytvoření efektů, převodníky formátů atd. Každý prvek roury má vlastnosti, které můžete použít ke změně jeho chování.</p>
  <media type="image" mime="image/png" src="media/guitar-tuner-pipeline.png">
    <p>Příklad roury systému GStreamer.</p>
  </media>
</section>

<section id="pipeline">
  <title>Vytvoření roury</title>
  <p>V tomto příkladu použijeme jako zdroj tónový generátor nazývaný <code>audiotestsrc</code> a výstup pošleme do výchozího systémového zvukového zařízení <code>autoaudiosink</code>. Nastavit nám stačí jen frekvenci tónového generátoru. Ta je přístupná v podobě vlastnosti <code>freq</code> u <code>audiotestsrc</code>.</p>

  <p>Musíme přidat řádek inicializující GStreamer. Vložte následující kód na řádek nad volání <code>Gtk.init</code> ve funkci <code>main</code>:</p>
  <code mime="text/x-csharp">Gst.init (ref args);</code>
  <p>Pak nakopírujte následující funkci do třídy <code>Main</code> v <file>guitar_tuner.vala</file>:</p>
  <code mime="text/x-csharp">
Gst.Element sink;
Gst.Element source;
Gst.Pipeline pipeline;

private void play_sound(double frequency)
{
	pipeline = new Gst.Pipeline ("note");
	source   = Gst.ElementFactory.make ("audiotestsrc",
	                                    "source");
	sink     = Gst.ElementFactory.make ("autoaudiosink",
	                                    "output");

	/* nastavení frekvence */
	source.set ("freq", frequency);

	pipeline.add (source);
	pipeline.add (sink);
	source.link (sink);

	pipeline.set_state (Gst.State.PLAYING);

	/* zastavení po 200 ms */
	var time = new TimeoutSource(200);

	time.set_callback(() =&gt; {
		pipeline.set_state (Gst.State.NULL);
		return false;
	});
	time.attach(null);
}</code>

  <steps>
    <item>
    <p>Prvních tři řádky vytvoří prvky GStreamer typu zdroj a cíl (<link href="http://valadoc.org/gstreamer-0.10/Gst.Element.html"><code>Gst.Element</code></link>) a <link href="http://valadoc.org/gstreamer-0.10/Gst.Pipeline.html">prvek typu roura</link> (který bude použit jako kontejner pro první dva prvky). Jedná se o proměnné třídy, takže jsou definovny mimo metodu. Roura dostane název „note“. Zdroj je pojmenován „source“ a je nastaven jako <code>audiotestsrc</code>. Cíl je pojmenován „output“ a je nastaven jako <code>autoaudiosink</code> (výchozí výstup zvukové karty).</p>
    </item>
    <item>
    <p>Volání <link href="http://valadoc.org/gobject-2.0/GLib.Object.set.html"><code>source.set_property</code></link> nastaví vlastnost <code>freq</code> prvku <code>source</code> na frekvenci <code>frequency</code>, která je předána jako argument do funkce <code>play_sound</code>. Jedná se o frekvenci v Hertzích. Správné frekvence nadefinujeme později.</p>
    </item>
    <item>
    <p><link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.add.html"><code>pipeline.add</code></link> vloží zdroj a cíl do roury. Roura je <link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.html"><code>Gst.Bin</code></link>, což je zase jen prvek, který může obsahovat více dalších prvků GStreamer. Obecně můžete přidat tolik prvků, kolik chcete, pomocí opakovaného volání <code>pipeline.add</code>.</p>
    </item>
    <item>
    <p>Následně je <link href="http://valadoc.org/gstreamer-0.10/Gst.Element.link.html"><code>sink.link</code></link> použito k propojení prvků navzájem, takže výstup prvku <code>source</code> (tón) putuje do vstupu prvku <code>sink</code> (což je výstup do zvukové karty). <link href="http://www.valadoc.org/gstreamer-0.10/Gst.Element.set_state.html"><code>pipeline.set_state</code></link> je použito ke spuštění přehrávání nastavením <link href="http://www.valadoc.org/gstreamer-0.10/Gst.State.html">stavu roury</link> na přehrávání (<code>Gst.State.PLAYING</code>).</p>
    </item>
    <item>
    <p>Nechceme ale hrát nějaký tón navždycky, takže poslední věcí, kterou <code>play_sound</code> udělá, je že přidá <link href="http://www.valadoc.org/glib-2.0/GLib.TimeoutSource.html"><code>TimeoutSource</code></link>. Tím se nastaví časový limit pro zastavení zvuku. Čeká 200 milisekund a pak zavolá obsluhu signálu definovanou jako vloženou, která zastaví a zlikviduje rouru. Ta vrací <code>false</code>, aby odstranila sebe sama z <code>TimeoutSource</code>, jinak by se pokračovalo v jejím volání každých 200 ms.</p>
    </item>
  </steps>
</section>


<section id="signal">
  <title>Vytvoření obsluhy signálů</title>
  <p>V návrháři uživatelského rozhraní to můžete udělat tak, že všechna tlačítka budou, když se na ně klikne, volat stejnou funkci <gui>on_button_clicked</gui>. Ve skutečnosti napíšeme <gui>main_on_button_clicked</gui>, což návrháři říká, že tato metoda je součástí <gui>Main</gui>. Tuto funkci musíme přidat do souboru se zdrojovým kódem.</p>
  <p>K tomuto účelu vyberte v souboru s uživatelským rozhraním (guitar_tuner.ui) kliknutím jedno z tlačítek a pak otevřete <file>guitar_tuner.vala</file> (kliknutím na kartu uprostřed). Přepněte se na kartu <gui>Signály</gui> napravo, kterou jste již použili pro nastavení názvu signálu. Nyní chytněte řádek, na kterém jste nastavili signál <gui>clicked</gui> a přetáhněte jej do zdrojového kódu na začátek třídy. Do zdrojového kódu se přidá následující kód:</p>
<code mime="text/x-csharp">
public void on_button_clicked (Gtk.Button odesilatel) {

}</code>

 <note><p>Místo přetahování z návrháře můžete kód samozřejmě také napsat ručně na začátek třídy.</p></note>
  <p>Tato obsluha signálu má jen jeden argument: <link href="http://valadoc.org/gtk+-3.0/Gtk.Widget.html"><code>Gtk.Widget</code></link>, který je volán funkcí (v našem případě vždy <link href="http://valadoc.org/gtk+-3.0/Gtk.Button.html"><code>Gtk.Button</code></link>).</p>
</section>


<section id="handler">
  <title>Definování obsluhy signálů</title>
  <p>Když uživatel klikne na tlačítko, chceme přehrát správný zvuk. To znamená, že musíme oživit obsluhu signálu  <code>on_button_clicked</code>, kterou jsem zadeklarovali již dříve. Mohli bychom mít napojená všechna tlačítka na různé obslužné funkce, ale to by vedlo ke zbytečné duplicitě kódu. Místo toho použijeme popisek každého z tlačítek ke zjištění, na které tlačítko bylo kliknuto:</p>
  <code mime="text/x-csharp">
public void on_button_clicked (Gtk.Button sender) {
	var label = sender.get_child () as Gtk.Label;
	switch (label.get_label()) {
		case "E":
			play_sound (329.63);
			break;
		case "A":
			play_sound (440);
			break;
		case "D":
			play_sound (587.33);
			break;
		case "G":
			play_sound (783.99);
			break;
		case "B":
			play_sound (987.77);
			break;
		case "e":
			play_sound (1318);
			break;
		default:
			break;
	}
}
</code>
  <p>Tlačítko <code>Gtk.Button</code>, na které bylo kliknuto, je předáno jako argument (<code>odesilatel</code>) do <code>on_button_clicked</code>. Pomocí <code>get_child</code> můžeme získat popisek tohoto tlačítka a z něj následně získat jeho text pomocí <code>get_label</code>.</p>
  <p>Výraz <code>switch</code> porovnává text popisku s notami, které chceme zahrát a funkce <code>play_sound</code> je zavolána s příslušnou frekvencí pro tuto notu. Tím se přehraje tón – máme funkční kytarovou ladičku!</p>
</section>

<section id="run">
  <title>Sestavení a spuštění aplikace</title>
  <p>Celý kód by nyní měl být připravený k fungování. Klikněte na <guiseq><gui>Sestavit</gui> <gui>Sestavit projekt</gui></guiseq>, aby se vše znovu sestavilo a pak na <guiseq><gui>Spustit</gui> <gui>Spustit</gui></guiseq>, aby se aplikace spustila.</p>
  <p>Pokud jste tak ještě neučinili, zvolte aplikaci <file>Debug/src/guitar-tuner</file> v dialogovém okně, které se objeví. Nakonec klikněte na <gui>Spustit</gui> a užijte si ji!</p>
</section>

<section id="impl">
 <title>Ukázková implementace</title>
 <p>Pokud v této lekci narazíte na nějaké problémy, porovnejte si svůj kód s tímto <link href="guitar-tuner/guitar-tuner.vala">ukázkovým kódem</link>.</p>
</section>

<section id="further">
<title>Co dalšího si přečíst</title>
<p>Jestli si chcete najít více o programování v jazyce Vala, můžete se podívat na <link href="http://live.gnome.org/Vala/Tutorial">Výuku jazyka Vala</link> a <link href="http://valadoc.org/">Dokumentaci k API jazyka Vala</link>.</p>
</section>

<section id="next">
  <title>Další postup</title>
  <p>Zde je pár nápadů, jak byste mohli tuto jednoduchou ukázku rozšířit:</p>
  <list>
   <item>
   <p>Přidat do programu možnost dokola procházet tóny.</p>
   </item>
   <item>
   <p>Naučit program přehrávat nahrávky vybrnkání jednotlivých reálných kytarových strun.</p>
   <p>Abychom to mohli udělat, potřebujeme sestavit mnohem složitější rouru GStreamer, která umožní načíst a přehrát hudební soubory. Budete muset zvolit prvky GStreamer typu <link href="http://gstreamer.freedesktop.org/documentation/plugins.html">dekodér a demultiplexor</link> podle formátu souborů s vašimi zvukovými nahrávkami – například MP3 používá jiné prvky než Ogg Vorbis.</p>
   <p>Můžete také potřebovat prvky propojit mnohem komplikovanějším způsobem. Toho lze dosáhnout pomocí <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-intro-basics.html">konceptů GStreamer</link>, které jsme v této lekci neprobírali. Mezi ně patří například <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-pads.html">přípojné body</link>. Hodit se vám může také příkaz <cmd>gst-inspect</cmd>.</p>
   </item>
   <item>
   <p>Automaticky analyzovat tóny, které uživatel zahraje.</p>
   <p>Mohli byste připojit mikrofón a nahrávat z něj zvuky pomocí <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-autoaudiosrc.html">vstupního zdroje</link>. Zjistit, který tón je přehráván, by vám možná pomohla <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-plugin-spectrum.html">spektrální analýza</link>.</p>
   </item>
  </list>
</section>

</page>
