GNOME.org
 

[gnome-devel-docs] JS tutorials: reworked helloWorld program

commit a0f52beafc9dbb136963eeb4bce77d73ad28c836
Author: Tiffany Antopolski <tiffany antopolski gmail com>
Date:   Tue Aug 14 16:25:33 2012 -0400

    JS tutorials: reworked helloWorld program

 platform-demos/C/desktop.js.page                   |   45 ------
 platform-demos/C/helloWorld.js.page                |  149 +++++++++++++++-----
 platform-demos/C/helloworldautotools.js.page       |   62 --------
 .../C/media/{helloWorldJs.png => helloWorld.png}   |  Bin 4817 -> 4817 bytes
 platform-demos/C/samples/helloWorld/Makefile.am    |   11 ++
 platform-demos/C/samples/helloWorld/README         |   35 +++++
 platform-demos/C/samples/helloWorld/autogen.sh     |   18 +++
 platform-demos/C/samples/helloWorld/configure.ac   |    5 +
 platform-demos/C/samples/helloWorld/helloWorld     |   42 ++++++
 .../C/samples/helloWorld/helloWorld.desktop.in     |   11 ++
 platform-demos/Makefile.am                         |   10 +-
 11 files changed, 240 insertions(+), 148 deletions(-)
---
diff --git a/platform-demos/C/helloWorld.js.page b/platform-demos/C/helloWorld.js.page
index 31be53d..f8ca130 100644
--- a/platform-demos/C/helloWorld.js.page
+++ b/platform-demos/C/helloWorld.js.page
@@ -3,8 +3,10 @@
       xmlns:xi="http://www.w3.org/2001/XInclude";
       type="guide" style="task"
       id="helloWorld.js">
+
   <info>
     <link type="guide" xref="beginner.js#tutorials" group="#first"/>
+
     <revision version="0.1" date="2012-02-19" status="stub"/>
 
     <credit type="author copyright">
@@ -19,32 +21,41 @@
 
     <desc>A basic "hello, world" application</desc>
   </info>
- <title>Hello World</title>
-   <synopsis>
-    <p>This tutorial will demonstrate how to make a small "Hello, World" application using JavaScript and GTK+.</p>
-  </synopsis>
-
-  <media type="image" mime="image/png" src="media/helloWorldJs.png"/>
-   <links type="section" />
-   <section id="script">
-    <title>Script for running the application</title>
-    <code mime="text/javascript"><![CDATA[
-#!/usr/bin/gjs]]></code>
-    <p>This needs to be the first line of your script. It tells the script to use <link href="https://live.gnome.org/Gjs/";>Gjs</link>. Gjs is a JavaScript binding for GNOME.</p>
-  </section>
 
-  <section id="imports">
-    <title>Libraries to import</title>
-    <code mime="text/javascript"><![CDATA[
-const Lang = imports.lang;
+  <title>Hello World</title>
+    <media type="image" mime="image/png" style="floatend" src="media/helloWorldJs.png"/>
+    <synopsis>
+      <p>This tutorial will demonstrate how to:</p>
+      <list style="numbered">
+        <item><p>create a small "Hello, World" application using JavaScript and GTK+</p></item>
+        <item><p>make the <file>.desktop</file> file</p></item>
+        <item><p>how to set up the build system</p></item>
+      </list>
+    </synopsis>
+
+
+
+  <links type="section" />
+
+  <section id="HelloWorld"><title>Create the HelloWorld program</title>
+
+    <links type="section" />
+
+    <section id="script"><title>Script for running the application</title>
+      <p>This needs to be the first line of your script:</p>
+      <code mime="text/javascript"><![CDATA[#!/usr/bin/gjs]]></code>
+      <p>It tells the script to use <link href="https://live.gnome.org/Gjs/";>Gjs</link>. Gjs is a JavaScript binding for GNOME.</p>
+    </section>
+
+
+    <section id="imports"><title>Libraries to import</title>
+      <code mime="text/javascript"><![CDATA[const Lang = imports.lang;
 const Gtk = imports.gi.Gtk;]]></code>
-    <p>In order for our script to work with GNOME, we need to import GNOME libraries via GObject Introspection. Here we import the language bindings and GTK+, the library which contains the graphical widgets used to make GNOME applications.  </p>
+      <p>In order for our script to work with GNOME, we need to import GNOME libraries via GObject Introspection. Here we import the language bindings and GTK+, the library which contains the graphical widgets used to make GNOME applications.  </p>
     </section>
 
-   <section id="mainwindow">
-    <title>Creating the main window for the application</title>
-    <code mime="text/javascript"><![CDATA[
-const Application = new Lang.Class({
+    <section id="mainwindow"><title>Creating the main window for the application</title>
+      <code mime="text/javascript"><![CDATA[const Application = new Lang.Class({
     //A Class requires an explicit Name parameter. This is the Class Name.
     Name: 'Application',
 
@@ -82,30 +93,92 @@ const Application = new Lang.Class({
     <p>Now we have a window which has a title and a working "close" button. Let's add the actual "Hello World" text.</p>
     </section>
 
-    <section id="label">
-  <title>Label for the window</title>
-  <code mime="text/javascript"><![CDATA[
-// Add a label widget to your window
+    <section id="label"><title>Label for the window</title>
+      <code mime="text/javascript"><![CDATA[// Add a label widget to your window
 this.label = new Gtk.Label({ label: "Hello World" });
 this._window.add(this.label);
 this._window.set_default_size(200, 200);]]></code>
-  <p>A text label is one of the GTK+ widgets we can use, on account of having imported the GTK+ library. To use it, we create a new variable called label, and assign it a new Gtk.Label. Then we give it properties inside the curly braces {}. In this case, we're setting the text that the label will hold. Finally, we create and run the application:</p>
-<code mime="text/javascript"><![CDATA[
-//run the application
+
+      <p>A text label is one of the GTK+ widgets we can use, on account of having imported the GTK+ library. To use it, we create a new variable called label, and assign it a new Gtk.Label. Then we give it properties inside the curly braces {}. In this case, we're setting the text that the label will hold. Finally, we create and run the application:</p>
+
+      <code mime="text/javascript"><![CDATA[//run the application
 let app = new Application();
 app.application.run(ARGV);]]></code>
 
-  <p>Gtk.ApplicationWindow can only hold one widget at a time. To construct more elaborate programs you need to create a holder widget like Gtk.Grid inside the window, and then add all the other widgets to it.</p>
+      <p>Gtk.ApplicationWindow can only hold one widget at a time. To construct more elaborate programs you need to create a holder widget like Gtk.Grid inside the window, and then add all the other widgets to it.</p>
+   </section>
+
+
+    <section id="js"><title>helloWorld.js</title>
+      <p>The complete file:</p>
+      <code mime="text/javascript" style="numbered"><xi:include href="samples/helloWorld.js" parse="text"><xi:fallback/></xi:include></code>
+    </section>
+
+    <section id="terminal"><title>Running the application from terminal</title>
+      <p>To run this application, first save it as helloWorld.js. Then open Terminal, go to the folder where your application is stored and run:</p>
+      <screen><output style="prompt">$ </output><input>gjs helloWorld.js</input></screen>
+    </section>
   </section>
-  <section id="js">
-    <title>helloWorld.js</title>
-    <p>Here's what the completed program looks like.</p>
 
-<code mime="text/javascript" style="numbered"><xi:include href="samples/helloWorld.js" parse="text"><xi:fallback/></xi:include></code>
+
+
+  <section id="desktop.in"><title>The <file>.desktop.in</file> file</title>
+      <p>Running applications from the Terminal is useful at the beginning of the application making process. To have a fully working <link href= "http://library.gnome.org/admin/system-admin-guide/stable/mimetypes-9.html.en";>application integration</link> in GNOME 3 requires a desktop launcher. For this you need to create a  <file>.desktop</file> file. The <file>.desktop</file> file describes the application name, the used icon and various integration bits. A deeper insight to <file>.desktop</file> file can be found <link href= "http://developer.gnome.org/desktop-entry-spec/";>here</link>. The <file>.desktop.in</file> will create the <file>.desktop</file>.</p>
+
+  <note>
+       <p>Before continuing, resave <file>helloWorld.js</file> as <file>helloWorld</file>.  The run this in the command line:</p>
+      <screen><output style="prompt">$ </output><input>chmod +x helloWorld</input></screen>
+  </note>
+
+    <p>The example shows you the minimum requirements for a <code>.desktop.in</code> file.</p>
+    <code mime="text/desktop" style="numbered"><xi:include href="samples/helloWorld/helloWorld.desktop.in" parse="text"><xi:fallback/></xi:include></code>
+
+    <p>Now let's go through some parts of the  <code>.desktop.in</code> file.</p>
+    <list>
+      <item><p>Name: This is the application name.</p></item>
+      <item><p>Comment: A short description of the application.</p></item>
+      <item><p>Exec: Specifies a command to execute when you choose the application from the menu. In this example exec just tells where to find the <code>helloWorld</code> file and the file takes care of the rest.</p></item>
+      <item><p>Terminal: Specifies whether the command in the Exec key runs in a terminal window.</p></item>
+    </list>
+
+    <p>If you want your  <code>.desktop</code> file to exist as a part of the system, copy your  <code>.desktop</code> file to this directory: ~/.local/share/applications</p>
+
+    <p>To put your application into the appropriate category, you need to add the necessary categories to the Categories line. More information on the different categories can be found in the <link href = "http://standards.freedesktop.org/menu-spec/latest/apa.html";>menu spec</link>.</p>
+    <p>In this example we use an existing icon. For a custom icon you need to have a .svg file of your icon, store it to /usr/share/icons/hicolor/scalable/apps. Write the name of your icon file to the .desktop file, on line 7. More information on icons in: <link href="http://library.gnome.org/admin/system-admin-guide/stable/themes-11.html.en";> Installing Icons for Themes </link>, <link href="https://live.gnome.org/GnomeGoals/AppIcon";>Installing Icons for Themes</link> and <link href="http://freedesktop.org/wiki/Specifications/icon-theme-spec";>on freedesktop.org: Specifications/icon-theme-spec</link>.</p>
   </section>
-  <section id="terminal">
-  <title>Running the application from terminal</title>
-  <p>To run this application, first save it as helloWorld.js. Then open Terminal, go to the folder where your application is stored and run:</p>
-<screen><output style="prompt">$ </output><input>gjs helloWorld.js</input></screen>
+
+  <section id="autotools"><title>The build system</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>
+    <links type="section"/>
+
+      <section id="autogen"><title>autogen.sh</title>
+        <code mime="text/desktop" style="numbered"><xi:include href="samples/helloWorld/autogen.sh" parse="text"><xi:fallback/></xi:include></code>
+
+      <p><file>autogen.sh</file> file will install</p>
+      <p>After the <file>autogen.sh</file> file is ready and saved run:</p>
+      <screen><output style="prompt">$ </output><input>chmod +x autogen.sh</input></screen>
+    </section>
+
+
+    <section id="makefile"><title>Makefile.am</title>
+      <code mime="text/desktop" style="numbered"><xi:include href="samples/helloWorld/Makefile.am" parse="text"><xi:fallback/></xi:include></code>
     </section>
+
+
+    <section id="configure"><title>configure.ac</title>
+      <code mime="text/ac" style="numbered"><xi:include href="samples/helloWorld/configure.ac" parse="text"><xi:fallback/></xi:include></code>
+    </section>
+
+
+    <section id="readme"><title>README</title>
+       <p>Information user should read first. This file can be blank.</p>
+
+       <p>When you have the <file>helloWorld</file>, <file>helloWorld.desktop.in</file>, <file>Makefile.am</file>, <file>configure.ac</file> and <file>autogen.sh</file> files with correct information and rights, the <file>README</file> file can include the following instructions:</p>
+      <code mime="text/readme" style="numbered"><xi:include href="samples/helloWorld/README" parse="text"><xi:fallback/></xi:include></code>
+    </section>
+
+    <!-- TODO: How to make a custom icon with autotools -->
+
+  </section>
 </page>
diff --git a/platform-demos/C/media/helloWorldJs.png b/platform-demos/C/media/helloWorld.png
similarity index 100%
rename from platform-demos/C/media/helloWorldJs.png
rename to platform-demos/C/media/helloWorld.png
diff --git a/platform-demos/C/samples/helloWorld/Makefile.am b/platform-demos/C/samples/helloWorld/Makefile.am
new file mode 100644
index 0000000..963c67c
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/Makefile.am
@@ -0,0 +1,11 @@
+# The actual runnable program is set to the SCRIPTS primitive.
+# # Prefix bin_ tells where to copy this
+bin_SCRIPTS = helloWorld
+# # List of files to be distributed
+EXTRA_DIST=  \
+	$(bin_SCRIPTS)
+#
+#     # The desktop files
+desktopdir = $(datadir)/applications
+desktop_DATA = \
+	helloWorld.desktop
diff --git a/platform-demos/C/samples/helloWorld/README b/platform-demos/C/samples/helloWorld/README
new file mode 100644
index 0000000..97d4148
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/README
@@ -0,0 +1,35 @@
+To build and install this program:
+
+./autogen.sh --prefix=home/path/to/directory/you/want/to/install
+make install
+
+-------------
+Running the first line above creates the following files:
+
+aclocal.m4
+autom4te.cache
+config.log
+config.status
+configure
+helloWorld.desktop
+install-sh
+missing
+Makefile.in
+Makefile
+
+Running "make install", installs the application in home/path/to/directory/you/want/to/install/bin
+and install the helloWorld.desktop file in home/path/to/directory/you/want/to/install/share/applications
+
+You can now run the application by typeing "Hello World" in the Overview.
+
+----------------
+To uninstall, type:
+
+make uninstall
+
+----------------
+To create a tarball type:
+
+make distcheck
+
+This will create hello-world-1.0.tar.xz
diff --git a/platform-demos/C/samples/helloWorld/autogen.sh b/platform-demos/C/samples/helloWorld/autogen.sh
new file mode 100755
index 0000000..cb2570e
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/autogen.sh
@@ -0,0 +1,18 @@
+#!/bin/sh
+
+set -e
+
+test -n "$srcdir" || srcdir=`dirname "$0"`
+test -n "$srcdir" || srcdir=.
+
+olddir=`pwd`
+cd "$srcdir"
+
+# This will run autoconf, automake, etc. for us
+autoreconf --force --install
+
+cd "$olddir"
+
+if test -z "$NOCONFIGURE"; then
+  "$srcdir"/configure "$@"
+fi
diff --git a/platform-demos/C/samples/helloWorld/configure.ac b/platform-demos/C/samples/helloWorld/configure.ac
new file mode 100644
index 0000000..075cac0
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/configure.ac
@@ -0,0 +1,5 @@
+# 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 dist-xz no-dist-gzip])
+AC_CONFIG_FILES([Makefile helloWorld.desktop])
+AC_OUTPUT
diff --git a/platform-demos/C/samples/helloWorld/helloWorld b/platform-demos/C/samples/helloWorld/helloWorld
new file mode 100755
index 0000000..3041dd1
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/helloWorld
@@ -0,0 +1,42 @@
+#!/usr/bin/gjs
+
+const Lang = imports.lang;
+const Gtk = imports.gi.Gtk;
+
+const Application = new Lang.Class({
+    //A Class requires an explicit Name parameter. This is the Class Name.
+    Name: 'Application',
+
+    //create the application
+    _init: function() {
+        this.application = new Gtk.Application();
+
+       //connect to 'activate' and 'startup' signals to handlers.
+       this.application.connect('activate', Lang.bind(this, this._onActivate));
+       this.application.connect('startup', Lang.bind(this, this._onStartup));
+    },
+
+    //create the UI
+    _buildUI: function() {
+        this._window = new Gtk.ApplicationWindow({ application: this.application,
+                                                   title: "Hello World!" });
+        this._window.set_default_size(200, 200);
+        this.label = new Gtk.Label({ label: "Hello World" });
+        this._window.add(this.label);
+    },
+
+    //handler for 'activate' signal
+    _onActivate: function() {
+        //show the window and all child widgets
+        this._window.show_all();
+    },
+
+    //handler for 'startup' signal
+    _onStartup: function() {
+        this._buildUI();
+    }
+});
+
+//run the application
+let app = new Application();
+app.application.run(ARGV);
diff --git a/platform-demos/C/samples/helloWorld/helloWorld.desktop.in b/platform-demos/C/samples/helloWorld/helloWorld.desktop.in
new file mode 100644
index 0000000..a96d438
--- /dev/null
+++ b/platform-demos/C/samples/helloWorld/helloWorld.desktop.in
@@ -0,0 +1,11 @@
+[Desktop Entry]
+Version=1.0
+Encoding=UTF-8
+Name=Hello World
+Comment=Say Hello
+Exec= prefix@/bin/helloWorld
+Icon=application-default-icon
+Terminal=false
+Type=Application
+StartupNotify=true
+Categories=GNOME;GTK;Utility;
diff --git a/platform-demos/Makefile.am b/platform-demos/Makefile.am
index 4e04f3a..fb3a607 100644
--- a/platform-demos/Makefile.am
+++ b/platform-demos/Makefile.am
@@ -67,6 +67,12 @@ demo_sources = \
 	samples/GtkApplicationWindow.py		\
 	samples/GtkApplicationWindow.vala	\
 	samples/helloWorld.js			\
+	samples/helloWorld/autogen.sh		\
+	samples/helloWorld/configure.ac		\
+	samples/helloWorld/helloWorld		\
+	samples/helloWorld/helloWorld.desktop.in\
+	samples/helloWorld/Makefile.am		\
+	samples/helloWorld/README		\
 	samples/image.c				\
 	samples/image.py			\
 	samples/image.vala			\
@@ -178,7 +184,7 @@ DOC_FIGURES = \
 	media/guitar-tuner.png			\
 	media/guitar-tuner-glade.png		\
 	media/guitar-tuner-pipeline.png		\
-	media/helloWorldJs.png			\
+	media/helloWorld.png			\
 	media/image.png				\
 	media/image-viewer.png			\
 	media/label.png				\
@@ -252,7 +258,6 @@ DOC_PAGES =				\
 	combobox.vala.page		\
 	combobox_multicolumn.py.page	\
 	cpp.page			\
-	desktop.js.page			\
 	dialog.c.page			\
 	dialog.js.page			\
 	dialog.py.page			\
@@ -283,7 +288,6 @@ DOC_PAGES =				\
 	guitar-tuner.py.page		\
 	guitar-tuner.vala.page		\
 	helloWorld.js.page		\
-	helloworldautotools.js.page	\
 	image.c.page			\
 	image.py.page			\
 	image.vala.page			\
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]