Image viewer

Before you start coding, you'll need to set up a new project in Anjuta. This will create all of the files you need to build and run the code later on. It's also useful for keeping everything together.

Before we start writing the image viewer, let's find out more about the way JavaScript is used in GNOME. Of course, your very first contact with any programming language should be the Hello World program which can already be found in main.js:

print ("Hello world!");

This should look quite natural if you're familiar with almost any other programming language. The function print is called with the argument "Hello world!", which will be printed on the screen. Note that each line of code ends with a semicolon.

This is the standard way to define a class in JavaScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

function MyClass () {
  this._init ();
}

MyClass.prototype = {

  _init: function () {
    this.propertyA = "This is an object's field";
    this.propertyB = 10;
  },

  aMethod: function (arg1, arg2) {
    print ("inside aMethod: " + arg1 + " " + arg2);
  },

  dumpProperties: function () {
    print (this.propertyA);
    print (this.propertyB);
  }

}

This defines a class called MyClass. Let's go through each part of the class definition:

Now that MyClass has been defined, we can play with it:

1
2
3
4

var o = new MyClass ();
o.aMethod ("Hello", "world");
o.propertyA = "Just changed its value!";
o.dumpProperties ();

This code creates a new instance of the class called o, runs aMethod, changes propertyA to a different string, and then calls dumpProperties (which outputs the fields).

Save the code in the main.js and then run it by using Run ▸ Execute from the menu or using the toolbar.

Let's see what a very basic Gtk application looks like in JavaScript:

1
2
3
4
5
6
7
8

const Gtk = imports.gi.Gtk;

Gtk.init (null, null);

var w = new Gtk.Window ({title: "Image Viewer Demo"});
w.show ();

Gtk.main ();

Let's take a look at what's happening:

Save the code in main.js and run it. You will notice that the application does not quit when you close the window. This is because we haven't set up a signal handler to deal with the window's destroy (close) signal yet. We'll do this shortly, but for now you can just hit Ctrl+C in the terminal window to quit the program.

The proper way of doing Gtk programming is by using classes. Let's rewrite the simple code you just wrote using classes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const Gtk = imports.gi.Gtk;

function ImageViewer () {
  this._init ();
}

ImageViewer.prototype = {
  _init: function () {
    this.window = new Gtk.Window ({title: "Image Viewer Demo"});
    this.window.show ();
  }
}

Gtk.init (null, null);
var iv = new ImageViewer ();
Gtk.main ();

Notice that the program is the same; we just moved the window creation code to our own ImageViewer class. The class's constructor calls the _init method, which creates and shows the window. We then create an instance of the class before running the main loop (Gtk.main).

This code is modular and can be split into multiple files easily. This makes it cleaner and easier to read.

Signals are one of the key concepts in Gtk programming. Whenever something happens to an object, it emits a signal; for example, when a button is clicked it gives off the clicked signal. If you want your program to do something when that event occurs, you must connect a function (a "signal handler") to that signal. Here's an example:

1
2
3
4
5

function button_clicked () {
  print ("you clicked me!");
}
var b = new Gtk.Button ({label:"Click me"});
b.connect ("clicked", button_clicked);

The last two lines create a Gtk.Button called b and connect its clicked signal to the button_clicked function, which is defined above. Every time the button is clicked, the code in the button_clicked function will be executed. It just prints a message here.

The syntax for connecting any signal to a function is:

object.connect (<signal_name>, <function_to_be_called>);

You can find signal definitions for any object in the GTK class reference.

b.connect ("clicked", function () { print ("you clicked me!"); });

When you close a Gtk window it's not really closed, it's hidden. This allows you to keep the window around (which is useful if you want to ask the user if they really want to close the window, for example).

In our case, we really do just want to close the window. The simplest way of doing this is by connecting the hide signal of the GtkWindow object to a function that closes the application. Go back to the image-viewer.js file and add the following code to the _init method, on the line above this.window.show:

1

this.window.connect ("hide", Gtk.main_quit);

This connects the hide signal of the window to Gtk's main_quit function, which ends the execution of the Gtk main loop. Once the main loop finishes, the function Gtk.main returns. Our program would continue to run any code written after the Gtk.main (); line, but since we don't have any code after that point, the program just ends.

Widgets (controls, such as buttons and labels) can be arranged in the window by making use of containers. You can organize the layout by mixing different types of containers, like boxes and grids.

A Gtk.Window is itself a type of container, but you can only put one widget directly into it. We would like to have two widgets, an image and a button, so we must put a "higher-capacity" container inside the window to hold the other widgets. A number of container types are available, but we will use a Gtk.Box here. A Gtk.Box can hold several widgets, organized horizontally or vertically. You can do more complicated layouts by putting several boxes inside another box and so on.

Let's add the box and widgets to the window. Insert the following code into the _init method, immediately above the this.window.show line:

1
2

var main_box = new Gtk.Box ({orientation: Gtk.Orientation.VERTICAL, spacing: 0});
this.window.add (main_box);

The first line creates a Gtk.Box called main_box and sets two of its properties: the orientation is set to vertical (so widgets are arranged in a column), and the spacing between the widgets is set to 0 pixels. The next line then adds the newly-created Gtk.Box to the window.

So far the window only contains an empty Gtk.Box, and if you run the program now you will see no changes at all (the Gtk.Box is a transparent container, so you can't see that it's there).

To add some widgets to the Gtk.Box, insert the following code directly below the this.window.add (main_box) line:

1
2

this.image = new Gtk.Image ();
main_box.pack_start (this.image, true, true, 0);

The first line creates a new Gtk.Image called image, which will be used to display an image file. Then, the image widget is added (packed) into the main_box container using Gtk.Box's pack_start method.

pack_start takes 4 arguments: the widget that is to be added to the Gtk.Box (child); whether the Gtk.Box should grow larger when the new widget is added (expand); whether the new widget should take up all of the extra space created if the Gtk.Box gets bigger (fill); and how much space there should be, in pixels, between the widget and its neighbors inside the Gtk.Box (padding).

Gtk containers (and widgets) dynamically expand to fill the available space, if you let them. You don't position widgets by giving them a precise x,y-coordinate location in the window; rather, they are positioned relative to one another. This makes handling window resizing much easier, and widgets should automatically take a sensible size in most situations.

Also note how the widgets are organized in a hierarchy. Once packed in the Gtk.Box, the Gtk.Image is considered a child of the Gtk.Box. This allows you to treat all of the children of a widget as a group; for example, you could hide the Gtk.Box, which would also hide all of its children at the same time.

Now insert these two lines, below the two you just added:

1
2

var open_button = new Gtk.Button ({label: "Open a picture..."});
main_box.pack_start (open_button, false, false, 0);

These lines are similar to the first two, but this time they create a Gtk.Button and add it to main_box. Notice that we are setting the expand argument (the second one) to false here, whereas it was set to true for the Gtk.Image. This will cause the image to take up all available space and the button to take only the space it needs. When you maximize the window, the button size will remain the same, but the image size will increase, taking up all of the rest of the window.

Finally, we must change the this.window.show (); line to read:

this.window.show_all ();

This will show the child of the Gtk window, and all of its children, and its children's children, and so on. (Remember that Gtk widgets are all hidden by default.)

When the user clicks on the Open button, a dialog should appear so that the user can choose a picture. Once chosen, the picture should be loaded and shown in the image widget.

The first step is to connect the clicked signal of the button to a signal handler function, which we call _openClicked. Put this code immediately after the var open_button = new Gtk.Button line where the button was created:

open_button.connect ("clicked", Lang.bind (this, this._openClicked));

We are using the Lang JavaScript helper here. It allows us to connect a class method to the signal, rather than a plain function (without a class) which we had used before for the window's hide signal. Don't worry about this for now, it's just a technical detail. For it to work, you also need to put the following line at the top of the file:

const Lang = imports.lang;

Now we can create the _openClicked() method. Insert the following into the ImageViewer.prototype code block, after the _init method (and not forgetting the comma):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  _openClicked: function () {
    var chooser = new Gtk.FileChooserDialog ({title: "Select an image",
                                              action: Gtk.FileChooserAction.OPEN,
                                              transient_for: this.window,
                                              modal: true});
    chooser.add_button (Gtk.STOCK_CANCEL, 0);
    chooser.add_button (Gtk.STOCK_OPEN, 1);
    chooser.set_default_response (1);

    var filter = new Gtk.FileFilter ();
    filter.add_pixbuf_formats ();
    chooser.filter = filter;

    if (chooser.run () == 1)
      this.image.file = chooser.get_filename ();

    chooser.destroy ();
  }

This is a bit more complicated than anything we've attempted so far, so let's break it down:

All of the code you need should now be in place, so try running the code. That should be it; a fully-functioning image viewer (and a whistlestop tour of JavaScript and Gtk) in not much time at all!

If you run into problems with the tutorial, compare your code with this reference code.

Here are some ideas for how you can extend this simple demonstration: