1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<?xml version='1.0' encoding='UTF-8'?>
<page xmlns="http://projectmallard.org/1.0/"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
type="guide" style="task"
id="hello-world.js">
<info>
<title type="text">Hello World (JavaScript)</title>
<link type="guide" xref="beginner.js#tutorials" group="#first"/>
<revision version="0.1" date="2013-06-17" status="review"/>
<credit type="author copyright">
<name>Susanna Huhtanen</name>
<email its:translate="no">ihmis.suski@gmail.com</email>
<years>2012</years>
</credit>
<credit type="editor">
<name>Tiffany Antopolski</name>
<email its:translate="no">tiffany.antopolski@gmail.com</email>
</credit>
<desc>A basic "hello, world" application</desc>
</info>
<title>How to build, install and create a <file>tar.xz</file> of a Hello World program</title>
<media type="image" mime="image/png" style="floatend" src="media/hello-world.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 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="application/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="application/javascript"><![CDATA[const Lang = imports.lang;
imports.gi.versions.Gtk = '3.0'
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>
</section>
<section id="mainwindow"><title>Creating the main window for the application</title>
<code mime="application/javascript"><![CDATA[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!" });
},
//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();
}
});
]]></code>
<p>GtkApplication initializes GTK+. It also connects the <gui>x</gui> button that's automatically generated along with the window to the "destroy" signal.</p>
<p>We can start building our first window. We do this by creating a variable called <var>_window</var> and assigning it a new Gtk.ApplicationWindow.</p>
<p>We give the window a property called <var>title</var>. The title can be any string you want it to be. To be on the safe side, it's best to stick to UTF-8 encoding.</p>
<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="application/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="application/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>
</section>
<section id="js"><title>hello-world.js</title>
<p>The complete file:</p>
<code mime="application/javascript" style="numbered"><xi:include href="samples/hello-in-js/hello-world" 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 hello-world.js. Then open Terminal, go to the folder where your application is stored and run:</p>
<screen><output style="prompt">$ </output><input>gjs hello-world.js</input></screen>
</section>
</section>
<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 fully working <link href= "https://developer.gnome.org/integration-guide/stable/mime.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 into the <file>.desktop</file> file can be found <link href= "http://developer.gnome.org/desktop-entry-spec/">here</link>. The <file>.desktop.in</file> file will create the <file>.desktop</file>.</p>
<note>
<p>Before continuing, resave <file>hello-world.js</file> as <file>hello-world</file>. Then run this in the command line:</p>
<screen><output style="prompt">$ </output><input>chmod +x hello-world</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/hello-in-js/hello-world.desktop.in" parse="text"><xi:fallback/></xi:include></code>
<p>Save this as <file>hello-world.desktop.in</file>. Now let's go through some parts of the <code>.desktop.in</code> file.</p>
<terms>
<item><title>Name</title><p>The application name.</p></item>
<item><title>Comment</title><p>A short description of the application.</p></item>
<item><title>Exec</title><p>Specifies a command to execute when you choose the application from the menu. In this example exec just tells where to find the <file>hello-world</file> file and the file takes care of the rest.</p></item>
<item><title>Terminal</title><p>Specifies whether the command in the Exec key runs in a terminal window.</p></item>
</terms>
<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 specification</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, stored in <file>/usr/share/icons/hicolor/scalable/apps</file>. Write the name of your icon file to the .desktop.in file, on line 7. More information on icons in: <link href="https://wiki.gnome.org/Initiatives/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="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="application/x-shellscript" style="numbered"><xi:include href="samples/hello-in-js/autogen.sh" parse="text"><xi:fallback/></xi:include></code>
<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="application/x-shellscript" style="numbered"><xi:include href="samples/hello-in-js/Makefile.am" parse="text"><xi:fallback/></xi:include></code>
</section>
<section id="configure"><title>configure.ac</title>
<code mime="application/x-shellscript" style="numbered"><xi:include href="samples/hello-in-js/configure.ac" parse="text"><xi:fallback/></xi:include></code>
</section>
<section id="readme"><title>README</title>
<p>Information users should read first. This file can be blank.</p>
<p>When you have the <file>hello-world</file>, <file>hello-world.desktop.in</file>, <file>Makefile.am</file>, <file>configure.ac</file> and <file>autogen.sh</file> files with correct information and permissions, create a <file>README</file> file with installation instructions. Below is a sample of what suitable README instructions may look like:</p>
<code mime="text/readme" style="numbered"><xi:include href="samples/hello-in-js/README" parse="text"><xi:fallback/></xi:include></code>
</section>
<!-- TODO: How to make a custom icon with autotools -->
</section>
</page>
|
