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

  
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:

  <list type="numbered">

    <item>
Vytvořit základní projekt pomocí <link xref="getting-ready">IDE Anjuta</link>.
</item>

    <item>
Vytvořit jednoduché GUI v návrháři uživatelského rozhraní <app>Anjuta</app>.
</item>

    <item>
Používat knihovnu <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">GStreamer</link> k přehrávání zvuků.
</item>

  </list>

  
Abyste mohli pokračovat v této lekci, budete potřebovat následující:

  <list>

    <item>
Základní znalosti programovacího jazyka <link href="https://live.gnome.org/Vala/Tutorial">Vala</link>.
</item>

    <item>
Nainstalovanou kopii vývojářského studia <app>Anjuta</app>.
</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>

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

  <steps>

    <item>

    
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.

    </item>

    <item>

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

   	</item>

    <item>

    
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">gstreamer-0.10</link>, aby se knihovna GStreamer zahrnula do vašeho projektu. Klikněte na <gui>Pokračovat</gui>.

    </item>

    <item>

    
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:

using GLib;

using Gtk;

    </item>

  </steps>

</section>

<section id="build">

  <title>Prvotní sestavení kódu</title>

  
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:

  <list>

  <item>

    
Dva řádky using importují jmenné prostory, takže je nebudeme muset výslovně uvádět.

   </item>

   <item>

    
Konstruktor třídy Main 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.

    <note>

    
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 on_destroy (a ukončení aplikace) při zavření okna.

    </note>

   </item>

   <item>

    
Statická funkce main se spustí jako výchozí, když spustíte aplikaci napsanou v jazyce Vala. Volá pár funkcí, které vytvoří třídu Main a nastaví a spustí aplikaci. Funkce Gtk.main spustí hlavní smyčku GTK, která spustí uživatelské rozhraní a začne naslouchat událostem (jako je kliknutí nebo zmáčknutí klávesy).

   </item>

  </list>

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

</section>

<section id="ui">

  <title>Vytvoření uživatelského rozhraní</title>

  
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.

  
Rozvržení každého uživatelského rozhraní v GTK+ je provedeno pomocí boxů a mřížek. Zde použijeme svislý GtkButtonBox, do kterého přiřadíme šest GtkButtons, jedno pro každou z kytarových strun.

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

  <steps>

   <item>

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

 <note>
Můžete také změnit <gui>Počet prvků</gui> a <gui>Orientaci</gui> na kartě <gui>Obecné</gui> napravo.
</note>

   </item>

   <item>

    
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.

   </item>

   <item>

    
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.

  <note>
Karta <gui>Obecné</gui> se nachází v části <gui>Widgety</gui> napravo.
</note>

    </item>

    <item>

     
Přepněte se na kartu <gui>Signál</gui> v části <gui>Widgety</gui> napravo a podívejte se po signálu clicked 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 main_on_button_clicked do sloupce <gui>Obslužná rutina</gui> a zmáčknutím <key>Enter</key>.

    </item>

    <item>

    
Zopakujte předchozí kroky pro ostatní tlačítka, takže přidáte následujících 5 strun s názvy A, D, G, B a e.

    </item>

    <item>

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

    </item>

  </steps>

</section>

<section id="gstreamer">

  <title>Roury systému GStreamer</title>

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

  
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">rouru</link> obsahující různé prvky zpracující směrem od zdroje do cíle (výstupu). Zdrojem může být například soubor s obrázkem, videosoubor nebo hudební soubor, výstupem pak widget nebo zvuková karta.

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

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

    
Příklad roury systému GStreamer.

  </media>

</section>

<section id="pipeline">

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

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

  
Musíme přidat řádek inicializující GStreamer. Vložte následující kód na řádek nad volání Gtk.init ve funkci main:

  Gst.init (ref args);

  
Pak nakopírujte následující funkci do třídy Main v <file>guitar_tuner.vala</file>:

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(() => {

		pipeline.set_state (Gst.State.NULL);

		return false;

	});

	time.attach(null);

}

  <steps>

    <item>

    
Prvních tři řádky vytvoří prvky GStreamer typu zdroj a cíl (<link href="http://valadoc.org/gstreamer-0.10/Gst.Element.html">Gst.Element</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 audiotestsrc. Cíl je pojmenován „output“ a je nastaven jako autoaudiosink (výchozí výstup zvukové karty).

    </item>

    <item>

    
Volání <link href="http://valadoc.org/gobject-2.0/GLib.Object.set.html">source.set_property</link> nastaví vlastnost freq prvku source na frekvenci frequency, která je předána jako argument do funkce play_sound. Jedná se o frekvenci v Hertzích. Správné frekvence nadefinujeme později.

    </item>

    <item>

    
<link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.add.html">pipeline.add</link> vloží zdroj a cíl do roury. Roura je <link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.html">Gst.Bin</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í pipeline.add.

    </item>

    <item>

    
Následně je <link href="http://valadoc.org/gstreamer-0.10/Gst.Element.link.html">sink.link</link> použito k propojení prvků navzájem, takže výstup prvku source (tón) putuje do vstupu prvku sink (což je výstup do zvukové karty). <link href="http://www.valadoc.org/gstreamer-0.10/Gst.Element.set_state.html">pipeline.set_state</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í (Gst.State.PLAYING).

    </item>

    <item>

    
Nechceme ale hrát nějaký tón navždycky, takže poslední věcí, kterou play_sound udělá, je že přidá <link href="http://www.valadoc.org/glib-2.0/GLib.TimeoutSource.html">TimeoutSource</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í false, aby odstranila sebe sama z TimeoutSource, jinak by se pokračovalo v jejím volání každých 200 ms.

    </item>

  </steps>

</section>

<section id="signal">

  <title>Vytvoření obsluhy signálů</title>

  
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.

  
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:

public void on_button_clicked (Gtk.Button odesilatel) {

}

 <note>
Místo přetahování z návrháře můžete kód samozřejmě také napsat ručně na začátek třídy.
</note>

  
Tato obsluha signálu má jen jeden argument: <link href="http://valadoc.org/gtk+-3.0/Gtk.Widget.html">Gtk.Widget</link>, který je volán funkcí (v našem případě vždy <link href="http://valadoc.org/gtk+-3.0/Gtk.Button.html">Gtk.Button</link>).

</section>

<section id="handler">

  <title>Definování obsluhy signálů</title>

  
Když uživatel klikne na tlačítko, chceme přehrát správný zvuk. To znamená, že musíme oživit obsluhu signálu  on_button_clicked, 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:

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;

	}

}

  
Tlačítko Gtk.Button, na které bylo kliknuto, je předáno jako argument (odesilatel) do on_button_clicked. Pomocí get_child můžeme získat popisek tohoto tlačítka a z něj následně získat jeho text pomocí get_label.

  
Výraz switch porovnává text popisku s notami, které chceme zahrát a funkce play_sound 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!

</section>

<section id="run">

  <title>Sestavení a spuštění aplikace</title>

  
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.

  
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!

</section>

<section id="impl">

 <title>Ukázková implementace</title>

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

</section>

<section id="further">

<title>Co dalšího si přečíst</title>

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

</section>

<section id="next">

  <title>Další postup</title>

  
Zde je pár nápadů, jak byste mohli tuto jednoduchou ukázku rozšířit:

  <list>

   <item>

   
Přidat do programu možnost cyklicky procházet tóny.

   </item>

   <item>

   
Naučit program přehrávat nahrávky vybrnkání jednotlivých reálných kytarových strun.

   
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.

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

   </item>

   <item>

   
Automaticky analyzovat tóny, které uživatel zahraje.

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

   </item>

  </list>

</section>

</page>