Getting Started

Simple Example

To start with our tutorial we create the simplest program possible. This program will create an empty 200 x 200 pixel window. Note that the appearance of the window will depend on your current GNOME theme.

_images/simple_example.png
1
2
3
4
5
6
7
8
9
#!/usr/bin/gjs

const Gtk = imports.gi.Gtk;
Gtk.init(null);

let win = new Gtk.Window();
win.connect("delete-event", Gtk.main_quit);
win.show_all();
Gtk.main();

We will now explain each line of the example.

We start the program with a shebang-directive, which tells the operating system what interpreter to use to execute the file.

1
#!/usr/bin/gjs

In the beginning, we have to import the Gtk module to be able to access GTK+’s classes and functions. Gtk is one of the libraries that make use of GObject introspection, and is therefore listed under the gi collection.

3
const Gtk = imports.gi.Gtk;

After we have imported Gtk, we must initialize it. In the Gtk bindings for many other languages, Gtk can be initialized with a list of strings, the list of arguments that was passed to the program (argv). This does not work in Gjs yet. As of now, Gtk.init must be initialized with a null argument.

4
Gtk.init(null);

The next line creates an empty window.

6
let win = new Gtk.Window();

Followed by connecting to the window’s delete event to ensure that the application is terminated if we click on the x to close the window.

7
win.connect("delete-event", Gtk.main_quit);

In the next step we display the window.

8
win.show_all();

Finally, we start the GTK+ processing loop which we quit when the window is closed.

9
Gtk.main();

You can now run the program by making it executable and executing it directly

chmod +x simple_example.js
./simple_example.js

or by running it with gjs

gjs simple_example.js

Extended Example

For something a little more useful, here’s the Gjs version of the classic “Hello World” program.

Attention: Old versions (like 1.46.0-1+b2 on Debian stable) of Gjs do not support classes, so the example does not work.

_images/extended_example.png
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/usr/bin/gjs

imports.gi.versions.Gtk = '3.0';
const {GObject, Gtk} = imports.gi;

Gtk.init(null);

const MyWindow = GObject.registerClass(class MyWindow extends Gtk.Window {
    _init() {
        super._init({ title: "Hello World" });
        this.button = new Gtk.Button({ label: "Click here" });
        this.button.connect("clicked", MyWindow.onButtonClicked);
        this.add(this.button);
    }

    static onButtonClicked() {
        print("Hello World");
    }
});

let win = new MyWindow();
win.connect("delete-event", () => Gtk.main_quit());
win.show_all();
Gtk.main();

This example differs from the simple example as we extend Gtk.Window to define our own MyWindow class. This would formerly be done by using the imports.lang library, which contained conventience methods for defining classes in an object oriented javascript-style, similar to MooTools. With later versions of Gjs, however, ES6-style classes are supported, but they must be registered using the GObject.registerClass call.

In the class’s constructor we have to call the constructor of the parent class, with an appropriate configuration object. In this case, we pass the title property, and set it to Hello World.

9
    _init() {

The next three lines are used to create a button widget, connect to its clicked signal and add it as child to the top-level window.

10
11
12
        super._init({ title: "Hello World" });
        this.button = new Gtk.Button({ label: "Click here" });
        this.button.connect("clicked", MyWindow.onButtonClicked);

Accordingly, the method onButtonClicked() will be called if you click on the button.

15
16
    static onButtonClicked() {
        print("Hello World");

Remember to register the class after its definition.

20

Instead of creating an instance of the generic Gtk.Window class, we create an instance of MyWindow.

22
23
24
win.connect("delete-event", () => Gtk.main_quit());
win.show_all();
Gtk.main();