[gnome-devel-docs: 1/4] Tutorials: Guitar tuner new, modifications to hello world
- From: Susanna Huhtanen <susannah src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-devel-docs: 1/4] Tutorials: Guitar tuner new, modifications to hello world
- Date: Fri, 9 Mar 2012 18:10:59 +0000 (UTC)
commit 710a850c33447785886b54b946bc699c51bc54e8
Author: Susanna Huhtanen <ihmis suski gmail com>
Date: Fri Mar 9 18:14:15 2012 +0100
Tutorials: Guitar tuner new, modifications to hello world
platform-demos/C/beginner.js.page | 2 +-
platform-demos/C/entry.js.page | 2 +-
platform-demos/C/guitar.js.page | 232 ++++++++++++++++++++++++++
platform-demos/C/helloWorld.js.page | 59 ++++++-
platform-demos/C/helloworldautotools.js.page | 61 +++++++
platform-demos/C/media/guitarJs.png | Bin 0 -> 10344 bytes
platform-demos/C/record-collection.js.page | 2 +-
platform-demos/Makefile.am | 7 +-
8 files changed, 357 insertions(+), 8 deletions(-)
---
diff --git a/platform-demos/C/beginner.js.page b/platform-demos/C/beginner.js.page
index 3e774b7..8c98fcb 100644
--- a/platform-demos/C/beginner.js.page
+++ b/platform-demos/C/beginner.js.page
@@ -18,7 +18,7 @@
<p>In these tutorials and samples we use JavaScript and GTK+. These tutorials and samples expect you to be familiar with the syntax of JavaScript, if not, read <link href="http://eloquentjavascript.net/contents.html";>Eloquent JavaScript</link> or your preferred guide to JavaScript. </p>
<section id="hello_world">
- <title>Hello World</title>
+ <title>Tutorials</title>
<p></p>
</section>
diff --git a/platform-demos/C/entry.js.page b/platform-demos/C/entry.js.page
index 096c155..4e3b2f8 100644
--- a/platform-demos/C/entry.js.page
+++ b/platform-demos/C/entry.js.page
@@ -32,7 +32,7 @@ myW.add(grid);
//create the entry widget
var entry = new Gtk.Entry();
-entry.set_text("Write something here");
+entry.set_placeholder_text("Write something here");
entry.set_width_chars(50);
//create the first label
var label = new Gtk.Label({label: "Entry widget: "});
diff --git a/platform-demos/C/guitar.js.page b/platform-demos/C/guitar.js.page
new file mode 100644
index 0000000..fa63499
--- /dev/null
+++ b/platform-demos/C/guitar.js.page
@@ -0,0 +1,232 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="guide" style="task"
+ id="guitar.js">
+ <info>
+ <link type="guide" xref="index#js"/>
+ <revision version="0.1" date="2012-03-09" status="stub"/>
+
+ <credit type="author copyright">
+ <name>Susanna Huhtanen</name>
+ <email>ihmis suski gmail com</email>
+ <years>2012</years>
+ </credit>
+
+ <desc>Use Gtk+ and GStreamer to build a simple guitar tuner application for GNOME.</desc>
+ </info>
+
+ <title>2 Guitar Tuner</title>
+
+ <synopsis>
+ <p>In this tutorial we'll construct a small application, Guitar Tuner, using JavaScript and GTK+ and GStreamer. To do and run all the code examples yourself, you need an editor to write code in, terminal and GNOME 3. or higher installed into your computer.</p>
+ <list>
+ <item><p> <link xref="#gstreamer">GStreamer pipelines</link> </p></item>
+ <item><p> <link xref="#script">Script for running the application</link> </p></item>
+ <item><p> <link xref="#imports">Libraries to import</link> </p></item>
+ <item><p> <link xref="#mainwindow">Creating the main window for the application</link> </p></item>
+ <item><p> <link xref="#buttons">Buttons for the tunes</link> </p></item>
+ <item><p> <link xref="#playSound">Making the sounds with GStreamer</link> </p></item>
+ <item><p> <link xref="#connecting">Connecting buttons to playSound</link> </p></item>
+ <item><p> <link xref="#guitarjs">The whole program</link> </p></item>
+ <item><p> <link xref="#terminal">Running the application form Terminal</link> </p></item>
+ </list>
+ </synopsis>
+ <p>After reading this tutorial, you should see this in your screen:</p>
+ <media type="image" mime="image/png" src="media/guitarJs.png"/>
+ <section id="gstreamer">
+ <title>GStreamer pipelines</title>
+ <p>GStreamer is GNOME's multimedia framework — you can use it for playing, recording, and processing video, audio, webcam streams and the like. Here, we'll be using it to produce single-frequency tones.</p>
+ <p>Conceptually, GStreamer works as follows: You create a <em>pipeline</em> containing several processing elements going from the <em>source</em> to the <em>sink</em> (output). The source can be an image file, a video, or a music file, for example, and the output could be a widget or the soundcard.</p>
+ <p>Between source and sink, you can apply various filters and converters to handle effects, format conversions and so on. Each element of the pipeline has properties which can be used to change its behaviour.</p>
+ <media type="image" mime="image/png" src="media/guitar-tuner-pipeline.png">
+ <p>An example GStreamer pipeline.</p>
+ </media>
+ </section>
+ <section id="script">
+ <title>Script for running the application</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+ #!/usr/bin/gjs]]></code>
+ <p> This line tells how to run the script. It needs to be the first line of the code and it needs to be executable. To get the execution rights go to terminal and run in right folder: chmod +x scriptname. Or you can use the graphical filemanager. Just go to the right folder where your code is, right click you code file, choose properties, click the permissions tab and check the box for allow executing file as a program
+ </p>
+ </section>
+ <section id="imports">
+ <title>Libraries to import</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+var Gtk = imports.gi.Gtk;
+var Gst = imports.gi.Gst;
+
+const Mainloop = imports.mainloop;]]></code>
+ <p>In order to have a working program we need to import a few GObject Introspection -libraries to our use. For working UI, we need Gtk and for Gstreamer to work we need Gst. These are imported in the beginning so we have them at use everywhere. Also in the beginning we import a construct Mainloop to handle the timeout to be used with the tuning sounds.</p>
+ </section>
+ <section id="mainwindow">
+ <title>Creating the main window for the application</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+Gtk.init(null, 0);
+Gst.init(null, 0);
+
+var guitarwindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL, border_width: 100});
+guitarwindow.title = "Guitar Tuner";
+guitarwindow.connect("destroy", function(){Gtk.main_quit()});
+
+guitarwindow.show();
+Gtk.main();]]></code>
+ <p>Importing Gtk and Gst is not enough, we need to initialize them in order to get them working. When Gtk and Gst are up and running we need to create the window for the application. Later we are going to put all the buttons for making sounds inside this window. In order to get the window showing, we need to tell it to show and we need also to run the code with the Gtk.main() </p>
+ </section>
+ <section id="buttons">
+ <title>Buttons for the tunes</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+var guitar_box = new Gtk.ButtonBox ({orientation: Gtk.Orientation.VERTICAL, spacing: 10});
+
+var E = new Gtk.Button({label: "E"});
+var A = new Gtk.Button({label: "A"});
+var D = new Gtk.Button({label: "D"});
+var G = new Gtk.Button({label: "G"});
+var B = new Gtk.Button({label: "B"});
+var e = new Gtk.Button({label: "e"});
+
+guitar_box.add(E);
+guitar_box.add(A);
+guitar_box.add(D);
+guitar_box.add(G);
+guitar_box.add(B);
+guitar_box.add(e);
+
+guitarwindow.add(guitar_box);
+
+guitar_box.show_all();]]></code>
+ <p>Because Gtk.Window can only contain a single widget, we need to create something under it to be able to add all the necessary buttons inside it. In this example we use Buttonbox. After creating the Buttonbox we create buttons with necessary labels. After we have the buttons we need to add them to the Buttonbox and the Buttonbox must be added to the Gtk.Window and everything in the Buttonbox must be shown.</p>
+ <p>After this stage you should have a window appearing to your screen showing 6 buttons. Right now the buttons don't do anything and we shall address that issue later. Before we can connect the button signals to something we need to code that something first. </p>
+ </section>
+ <section id="playSound">
+ <title>Making the sounds with GStreamer</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+var frequencies = {E: 369.23, A: 440, D: 587.33, G: 783.99, B: 987.77, e: 1318.5}
+
+function playSound(frequency){
+ var pipeline = new Gst.Pipeline({name: "note"});
+ var source = new Gst.ElementFactory.make("audiotestsrc","source");
+ var sink = new Gst.ElementFactory.make("autoaudiosink","output");
+
+ source.set_property('freq', frequency);
+ pipeline.add(source);
+ pipeline.add(sink);
+ source.link(sink);
+ pipeline.set_state(Gst.State.PLAYING);
+
+ Mainloop.timeout_add(500, function () {
+ pipeline.set_state(Gst.State.PAUSED);
+ return false;
+ });
+}]]></code>
+ <p>The first thing we need to do is decide what tunes we want to make when we push a button. The frequencies list takes care of that. After that we get to actually making the sounds with the function playSound. For function playSound we give as an input a frequency (that we just defined in the frequencies variable). First thing we need to construct is a pipeline, a source and a sink. For the source we set the frequency. To the pipeline we add both the source and the sink and then we tell it to keep playing. As a last thing we use the const Mainloop to get the pipeline to pause after a 500ms. </p>
+ <p>Now we have the method of playing a tune when clicking a button. Next well make the conncetions between pushing a button and playing the correct sound from that button.</p>
+ </section>
+ <section id="connecting">
+ <title>Connecting buttons to playSound</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+E.connect("clicked", function() {
+ playSound(frequencies.E);
+});
+A.connect("clicked", function(){
+ playSound(frequencies.A);
+});
+D.connect("clicked", function(){
+ playSound(frequencies.D);
+});
+G.connect("clicked", function(){
+ playSound(frequencies.G);
+});
+B.connect("clicked", function(){
+ playSound(frequencies.B);
+});
+e.connect("clicked", function(){
+ playSound(frequencies.e);
+});]]></code>
+ <p>The method of connecting button clicks to playSound with the correct tune is by using the connect method of the button widget. So we yelp-check validate *pagechoose a button to be connected and type E.connect("clicked", function(){playSound(frequencies.E);}); The connect tells that when pushing E, something should happen. The "clicked" tells the type of something happening to E and then in the function(){}; we the playSound happen with the correct tune that should be associated to the button.</p>
+ </section>
+ <section id="guitarjs">
+ <title>The whole program</title>
+ <p>So this is what all the parts combined looks like. When running this code, you should be able to tune your guitar(if you have correctly calibrated speakers).</p>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+#!/usr/bin/gjs
+var Gtk = imports.gi.Gtk;
+var Gst = imports.gi.Gst;
+
+const Mainloop = imports.mainloop;
+
+Gtk.init(null, 0);
+Gst.init(null, 0);
+
+var guitarwindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL, border_width: 100});
+guitarwindow.title = "Guitar Tuner";
+guitarwindow.connect("destroy", function(){Gtk.main_quit()});
+
+var guitar_box = new Gtk.ButtonBox ({orientation: Gtk.Orientation.VERTICAL, spacing: 10});
+
+var E = new Gtk.Button({label: "E"});
+var A = new Gtk.Button({label: "A"});
+var D = new Gtk.Button({label: "D"});
+var G = new Gtk.Button({label: "G"});
+var B = new Gtk.Button({label: "B"});
+var e = new Gtk.Button({label: "e"});
+
+var frequencies = {E: 369.23, A: 440, D: 587.33, G: 783.99, B: 987.77, e: 1318.5}
+
+
+function playSound(frequency){
+ var pipeline = new Gst.Pipeline({name: "note"});
+
+ var source = new Gst.ElementFactory.make("audiotestsrc","source");
+ var sink = new Gst.ElementFactory.make("autoaudiosink","output");
+
+ source.set_property('freq', frequency);
+ pipeline.add(source);
+ pipeline.add(sink);
+ source.link(sink);
+ pipeline.set_state(Gst.State.PLAYING);
+
+ Mainloop.timeout_add(500, function () {
+ pipeline.set_state(Gst.State.PAUSED);
+ return false;
+});
+}
+
+E.connect("clicked", function() {
+ playSound(frequencies.E);
+});
+A.connect("clicked", function(){
+ playSound(frequencies.A);
+});
+D.connect("clicked", function(){
+ playSound(frequencies.D);
+});
+G.connect("clicked", function(){
+ playSound(frequencies.G);
+});
+B.connect("clicked", function(){
+ playSound(frequencies.B);
+});
+e.connect("clicked", function(){
+ playSound(frequencies.e);
+});
+
+guitar_box.add(E);
+guitar_box.add(A);
+guitar_box.add(D);
+guitar_box.add(G);
+guitar_box.add(B);
+guitar_box.add(e);
+
+guitarwindow.add(guitar_box);
+
+guitar_box.show_all();
+guitarwindow.show();
+Gtk.main();]]></code>
+ </section>
+
+<section id="terminal">
+ <title>Running the application form Terminal</title>
+ <p>To run this application open Terminal, go to the folder where your application is stored and then run</p> <screen> <output style="prompt">$ </output><input> GJS_PATH=`pwd` gjs guitarTuner.js</input> </screen>
+ </section>
+
+
+</page>
diff --git a/platform-demos/C/helloWorld.js.page b/platform-demos/C/helloWorld.js.page
index 332ce1f..afc13cf 100644
--- a/platform-demos/C/helloWorld.js.page
+++ b/platform-demos/C/helloWorld.js.page
@@ -2,7 +2,7 @@
type="guide" style="task"
id="helloWorld.js">
<info>
- <link type="guide" xref="beginner.js#hello_world"/>
+ <link type="guide" xref="beginner.js#hello_world" group="#first"/>
<revision version="0.1" date="2012-02-19" status="stub"/>
<credit type="author copyright">
@@ -16,12 +16,62 @@
<title>Hello World</title>
<synopsis>
- <p>In this tutorial we'll construct a small application, Hello World, using JavaScript and GTK+. To do and run all the code examples yourself, you need an editor to write code in, terminal and GNOME 3. or higher installed into your computer.</p>
+ <p>In this tutorial we'll construct a small application, Hello World, using JavaScript and GTK+. To do and run all the code examples yourself, you need an editor to write code in, Terminal and GNOME 3 or higher installed into your computer. In this tutorial we'll go through the following parts:</p>
+ <list>
+ <item><p> <link xref="#script">Script for running the application</link> </p></item>
+ <item><p> <link xref="#imports">Libraries to import</link> </p></item>
+ <item><p> <link xref="#mainwindow">Creating the main window for the application</link> </p></item>
+ <item><p> <link xref="#label">Label for the window</link> </p></item>
+ <item><p> <link xref="#js">helloWorld.js</link> </p></item>
+ <item><p> <link xref="#terminal">Running the application form Terminal</link> </p></item>
+ </list>
+
</synopsis>
+ <p>After reading this tutorial, you should see this in your screen:</p>
+ <media type="image" mime="image/png" src="media/helloWorldJs.png"/>
+ <section id="script">
+ <title>Script for running the application</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+ #!/usr/bin/gjs]]></code>
+ <p> This line tells how to run the script. It needs to be the first line of the code and it needs to be executable. To get the execution rights go to terminal and run in right folder: chmod +x scriptname. Or you can use the graphical filemanager. Just go to the right folder where your code is, right click you code file, choose properties, click the permissions tab and check the box for allow executing file as a program
+ </p>
+ </section>
+ <section id="imports">
+ <title>Libraries to import</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+var Gtk = imports.gi.Gtk;]]></code>
+ <p>In order to have a working program we need to import a GObject Introspection -library to our use. For working UI, we need Gtk. Gtk is imported in the beginning so we have it in our use everywhere.</p>
+ </section>
+
+ <section id="mainwindow">
+ <title>Creating the main window for the application</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+// Initialize the gtk
+Gtk.init(null, 0);
+//create your window, name it and connect the x to quit function. Remember that window is a taken word
+var mywindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL});
+mywindow.title = "Hello World!";
+mywindow.connect("destroy", function(){Gtk.main_quit()});
+
+
+mywindow.show();
+//and run it
+Gtk.main();]]></code>
+ <p>After importing Gtk, we need to initialize it. After initializing Gtk we can start building our first window. We do this by creating a variable mywindow and assign it a new Gtk.Window of type TOPLEVEL.</p> <p>After setting up our first window we'll give the window a property called title. Title can be any string you want it to be, to be on the safe side it is good to stick to UTF-8 encoding.</p> <p>The next major improvement to our application is connecting the automatically with the window generated close button with a functionality. The close button has only one reasonable function and that is to close the window. The connecting happens with the method connect. The signal the window is listening to is "destroy", so when the close button is pressed it gives out the signal "destroy". Just listening the signal is not enough, it needs to launch an action. in this case we want it to close the window, so quit he main loop should do the trick. So after "destroy", we'll ad
function(){Gtk.main_quit()} to do the actual closing.</p><p>Now we have a window that has a title and a functionality of closing the window. If we would run th application at this stage it wouldnt show anything, so we need to tell our window to show itself with the method show() and we need to also run the whole application in order for anything to happen.</p>
+ </section>
+
+ <section id="label">
+ <title>Label for the window</title>
+ <code mime="text/javascript" style="numbered"><![CDATA[
+//Set some text to your window
+var label = new Gtk.Label({label: "Hello World"});
+mywindow.add(label);]]></code>
+ <p>Now all the hard parts are done. The only thing we need now is to put something inside our window. A label telling what this is about is the easiest thing to do, so we create a new variable called label and assign it a new Gtk.Lablel. With the label we're using a different method of giving it properties, we are giving the properties inside curly braces {}. The label has to be added to the window in order for the method show() applying also to it. For the future it is good to know that Gtk.Window can only contain one widget at the time. To be able to construct more elaborate programs you need to create a holder widget (Gtk.Box, Gtk.Grid, Gtk.Application and so on) of some kind under the window and then adding all the other widgets to that.</p>
+ </section>
<section id="js">
<title>helloWorld.js</title>
- <p>This a basic Hello World application done with JavaScript and GTK+.</p>
+ <p>This is what the whole program looks like.</p>
<code mime="text/javascript" style="numbered"><![CDATA[
#!/usr/bin/gjs
//The previous line is a hash bang tells how to run the script.
@@ -42,6 +92,9 @@ label.show();
mywindow.show();
//and run it
Gtk.main();]]></code>
+ </section>
+ <section id="terminal">
+ <title>Running the application form Terminal</title>
<p>To run this application open Terminal, go to the folder where your application is stored and then run</p> <screen> <output style="prompt">$ </output><input> GJS_PATH=`pwd` gjs helloWorld.js</input> </screen>
</section>
</page>
diff --git a/platform-demos/C/helloworldautotools.js.page b/platform-demos/C/helloworldautotools.js.page
new file mode 100644
index 0000000..0d1961b
--- /dev/null
+++ b/platform-demos/C/helloworldautotools.js.page
@@ -0,0 +1,61 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic" style="task"
+ id="helloworldautotools.js">
+ <info>
+ <link type="guide" xref="beginner.js#hello_world" group="#last"/>
+ <revision version="0.1" date="2012-02-21" status="stub"/>
+
+ <credit type="author copyright">
+ <name>Susanna Huhtanen</name>
+ <email>ihmis suski gmail com</email>
+ <years>2012</years>
+ </credit>
+
+ <desc></desc>
+ </info>
+
+ <title>Autotools files for your Hello World application</title>
+ <p>To make your application truly a part of the GNOME 3 system you need to install it with the help of autotools. The autotools build will install all the necessary files to all the right places. </p>
+ <p>For this you need to have the following files:</p>
+ <list>
+ <item><p>autogen.sh</p></item>
+ <item><p>Makefile.am</p></item>
+ <item><p>configure.ac</p></item>
+ <item><p>README</p></item>
+ </list>
+ <p>autogen.sh</p>
+ <code mime="text/sh" style="numbered"><![CDATA[
+#!/bin/sh
+# This will run autoconf, automake, etc. for us
+autoreconf --force --install]]></code>
+ <p>autogen.sh file will install</p>
+ <p>After the autogen.sh file is ready and saved run</p><screen> <output style="prompt">$ </output><input>chmod +x autogen.sh</input></screen><p>to give the file the necessary rights to install.</p>
+ <p>Makefile.am</p>
+ <code mime="text/am" style="numbered"><![CDATA[
+# The actual runnable program is set to the SCRIPTS primitive. Prefix bin_ tells where to copy this
+bin_SCRIPTS = helloworld.js
+# List of files to be distributed
+EXTRA_DIST= \
+ $(bin_SCRIPTS)
+
+# The desktop files
+desktopdir = $(datadir)/applications
+desktop_DATA = helloworld.desktop]]></code>
+ <p>configure.ac</p>
+ <code mime="text/ac" style="numbered"><![CDATA[
+dnl This file is processed by autoconf to create a configure script
+AC_INIT([Hello World], 1.0)
+AM_INIT_AUTOMAKE([1.10 no-define foreign])
+AC_CONFIG_FILES(Makefile)
+AC_OUTPUT]]></code>
+ <p>README: Information user should read first.</p>
+ <p>When you have all the 3 files with correct information and rights run these commands in terminal:</p>
+ <screen>
+ <output style="prompt">$ </output><input>./autogen.sh</input>
+ <output style="prompt">$ </output><input>./configure --prefix=/usr/local</input>
+ <output style="prompt">$ </output><input>sudo make install</input>
+ </screen>
+ <!-- TODO: uninstall -->
+ <!-- TODO: clean, the git thingie is rude -->
+ <!-- TODO: How to make a custom icon with autotools -->
+</page>
diff --git a/platform-demos/C/media/guitarJs.png b/platform-demos/C/media/guitarJs.png
new file mode 100644
index 0000000..aeabd8e
Binary files /dev/null and b/platform-demos/C/media/guitarJs.png differ
diff --git a/platform-demos/C/record-collection.js.page b/platform-demos/C/record-collection.js.page
index 913ada5..d752844 100644
--- a/platform-demos/C/record-collection.js.page
+++ b/platform-demos/C/record-collection.js.page
@@ -18,7 +18,7 @@
</credit>
</info>
-<title>Record Collection</title>
+<title>3 Record Collection</title>
<synopsis>
<p>In this tutorial, you will learn:</p>
diff --git a/platform-demos/Makefile.am b/platform-demos/Makefile.am
index 5b57a33..1e6036b 100644
--- a/platform-demos/Makefile.am
+++ b/platform-demos/Makefile.am
@@ -28,9 +28,11 @@ DOC_FIGURES = \
media/entry.png \
media/fedora.png \
media/opensuse.png \
+ media/guitarJs.png \
media/guitar-tuner.png \
media/guitar-tuner-glade.png \
media/guitar-tuner-pipeline.png \
+ media/helloWorldJs.png \
media/image-viewer.png \
media/message-board.ogv \
media/photo-wall.png \
@@ -52,6 +54,7 @@ DOC_PAGES = \
getting-ready.page \
guitar-tuner.c.page \
guitar-tuner.cpp.page \
+ guitar.js.page \
guitar-tuner.py.page \
guitar-tuner.vala.page \
helloWorld.js.page \
@@ -65,7 +68,7 @@ DOC_PAGES = \
message-board.c.page \
toolbar.js.page \
photo-wall.c.page \
- record-collection.js.page \
- translate.page
+ record-collection.js.page \
+ translate.page
dist-hook: doc-dist-hook
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
