# Image viewer (JavaScript)

A little bit more than a simple "Hello world" application - write an image viewer in GTK+. Includes an introduction to the JavaScript language.
Jonh Wendell
jwendell@gnome.org
Johannes Schmid
jhs@gnome.org
Marta Maria Casetti
mmcasettii@gmail.com 2013
Luc Rebert,
traduc@rebert.name 2011
Alain Lojewski,
allomervan@gmail.com 2011-2012
Luc Pionchon
pionchon.luc@gmail.com 2011
Bruno Brouard
annoa.b@gmail.com 2011-12
Luis Menina
liberforce@freeside.fr 2014

# Image viewer

      Dans ce tutoriel, nous allons écrire une application GTK très simple qui charge et affiche un fichier image. Vous allez apprendre comment :

        écrire une interface utilisateur GTK de base en JavaScript,
        travailler avec des événements en connectant des signaux à des gestionnaires de signaux,
        mettre en forme des interfaces utilisateur GTK avec des conteneurs,
        charger et afficher des fichiers image.

      Vous avez besoin de ce qui suit pour pouvoir suivre ce tutoriel :

        l'installation du paquet Anjuta IDE,
        une copie installée de l'interpréteur gjs,
        des connaissances de base d'un langage de programmation objet.

# Création d'un projet dans Anjuta

Avant de commencer à programmer, vous devez ouvrir un nouveau projet dans Anjuta. Ceci crée tous les fichiers qui vous sont nécessaires pour construire et exécuter votre programme plus tard. C'est aussi utile pour tout regrouper en un seul endroit.

Lancez Anjuta et cliquez sur FichierNouveauProjet pour ouvrir l'assistant de création de projet.

Sélectionnez JavaScript générique dans l'onglet JS, cliquez sur Continuer et saisissez vos informations sur les pages suivantes. Mettez visionneur_image comme nom de projet et de répertoire.

Cliquez sur Appliquer et le projet est créé. Ouvrez src/main.js depuis l'onglet Projet ou l'onglet Fichiers. Il contient un exemple de programme très basique.

# Les bases JavaScript : Hello World

Avant de commencer à programmer le visionneur d'images, regardons de plus près la façon dont JavaScript est utilisé dans GNOME. Bien sûr, votre tout premier contact avec n'importe quel langage de programmation devrait être le « Hello World » du fichier main.js :

print("Hello world!");

Ceci doit vous sembler très normal si vous êtes familier avec la plupart des langages de programmation. La fonction `print` est appelée avec l'argument `"Hello world!"` qui est imprimé à l'écran. Notez que chaque ligne du programme se termine par un point-virgule.

# Les classes en JavaScript

Voici la méthode standard pour définir une classe en JavaScript :

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); }

}

Ceci définit une classe appelée `MyClass`. Passons en revue chaque partie de la définition d'une classe :

`function MyClass` est le constructeur de la classe — son nom doit correspondre au nom de la classe. Vous avez accès à n'importe quel membre de la classe avec l'objet `this` ; ici, le générateur appelle la méthode `_init` de la classe.

Le bloc `MyClass.prototype` est l'endroit où vous définissez la structure de la classe. Chaque classe est constituée de méthodes (les fonctions) et de champs (les variables) ; il y a trois méthodes et deux champs dans cet exemple.

La première méthode définie ici est appelée `_init` et nous spécifions que c'est une fonction sans argument :

_init: function ()

Nous écrivons la fonction à l'intérieur d'accolades. Deux champs sont définis ici, `propertyA` et `propertyB`. Le premier est défini comme une chaîne et le second comme un nombre entier (10). La fonction ne retourne aucune valeur.

La méthode suivante est appelée `aMethod` et possède deux arguments qu'elle affiche quand vous l'appelez. La dernière méthode est `dumpProperties` et elle affiche les champs `propertyA` et `propertyB`.

Notez comment la définition de la classe (prototype) est structurée ; chaque définition de fonction est séparée par une virgule.

Maintenant que MyClass a été défini, nous pouvons jouer avec :

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

Ce code crée une nouvelle version de la classe appelée `o`, appelle `aMethod`, modifie `propertyA` en une chaîne différente et ensuite appelle `dumpProperties` (qui affiche les champs).

Enregistrez le code dans le fichier main.js et ensuite lancez-le avec ExécuterExécuter à partir du menu ou de la barre d'outils.

# Une première application Gtk

Voyons à quoi ressemble une application Gtk très basique écrite en JavaScript :

const Gtk = imports.gi.Gtk;

Gtk.init (null, null);

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

Gtk.main ();

Regardons ce qui se passe :

La première ligne importe l'espace de nom Gtk (c.-à-d. cela inclut la bibliothèque Gtk). Les bibliothèques sont fournies par « GObject Introspection (gi) » qui fournit les liens de langage à beaucoup de bibliothèques GNOME.

`Gtk.init` initialise la bibliothèque Gtk ; cette instruction est obligatoire pour tous les programmes Gtk.

La ligne suivante crée la fenêtre principale en créant un nouvel objet `Gtk.Window`. Vous pouvez transmettre plusieurs propriétés au constructeur de la fenêtre avec la syntaxe `{propriété: valeur, propriété: valeur, ...}`. Dans ce cas, le titre de la fenêtre est défini.

La ligne suivante affiche explicitement la fenêtre. Dans Gtk, chaque élément graphique est masqué par défaut.

Enfin, `Gtk.main` lance la boucle principale — en d'autres termes, il exécute le programme. La boucle principale écoute les événements (signaux) en provenance de l'interface utilisateur et appelle un gestionnaire de signal qui fera quelque chose d'utile. Nous en apprendrons davantage sur les signaux bientôt.

Enregistrez le code dans le fichier main.js et exécutez-le. Notez que l'application ne quitte pas quand vous fermez la fenêtre. C'est parce que nous n'avons pas encore défini de gestionnaire de signal qui prend en charge le signal `destroy` de fermeture. Nous le ferons prochainement, mais en attendant, pressez seulement CtrlC dans la fenêtre du terminal pour quitter le programme.

# Ajout de classes

La bonne méthode de programmation avec Gtk est l'utilisation de classes. Récrivons le bout de programme que l'on vient d'écrire en utilisant des classes :

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 ();

Notez que le programme reste le même ; on a juste déplacé le code de création de la fenêtre dans notre propre classe `ImageViewer`. Le constructeur de la classe appelle la méthode `_init` qui crée et affiche la fenêtre. Ensuite, on crée une instance de la classe avant de lancer la boucle principale (`Gtk.main`).

Ce programme est modulaire et peut être divisé facilement en plusieurs fichiers ce qui le rend plus propre et plus facile à lire.

# Les signaux

Les signaux sont un des concepts clé de la programmation Gtk. Chaque fois que quelque chose arrive à un objet, il émet un signal ; par exemple, quand un bouton est cliqué, il renvoie le signal `clicked`. Si vous voulez que votre programme réagisse en conséquence, il faut connecter une fonction (un « gestionnaire de signal ») à ce signal. Voici un exemple :

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

Les deux dernières lignes créent un bouton `Gtk.Button` appelé `b` et connectent son signal `clicked` à la fonction `button_clicked` définie au-dessus. Chaque fois que ce bouton est cliqué, le code de la fonction `button_clicked` est exécuté. Il affiche juste un message dans cet exemple.

Voici la syntaxe pour connecter n'importe quel signal à une fonction :

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

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

Vous pouvez simplifier le code avec une définition de fonction en ligne :

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

# Fermeture de la fenêtre

Quand vous fermez une fenêtre Gtk, elle n'est pas vraiment fermée, mais masquée. Cela permet de la garder accessible (utile si on veut poser la question à l'utilisateur s'il veut oui ou non fermer la fenêtre, par exemple).

Dans notre cas, on veut réellement fermer la fenêtre. La façon la plus simple de le faire est de connecter le signal `hide` de l'objet fenêtre « GtkWindow » à une fonction qui ferme l'application. Retournez au fichier image-viewer.js et ajoutez le code suivant à la méthode `_init` dans la ligne au-dessus de `this.window.show` :

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

Ceci connecte le signal `hide` de la fenêtre à la fonction `main_quit` de Gtk, qui met fin à l'exécution de la boucle principale de Gtk. Lorsque cette boucle s'arrête, la fonction `Gtk.main` est quittée. Notre programme aurait continué d'exécuter n'importe quel code écrit après la ligne `Gtk.main ();`, mais comme nous n'avons plus de code après cela, le programme s'arrête.

# Les conteneurs : agencement de l'interface utilisateur

Les éléments graphiques (les contrôles, comme les boutons ou les étiquettes) peuvent être disposés dans la fenêtre à l'aide de conteneurs. Vous pouvez organiser l'agencement en mélangeant différents types de conteneurs, comme des boîtes ou des grilles.

Une fenêtre `Gtk.Window` est elle-même un type de conteneur, mais vous ne pouvez y insérer directement qu'un seul élément graphique. Nous aimerions avoir deux éléments graphiques, une image et un bouton, donc nous devons placer un conteneur de « plus haute capacité » dans la fenêtre pour tout contenir. Plusieurs types de conteneurs sont disponibles, mais nous allons utiliser ici une boîte `Gtk.Box`. Une boîte `Gtk.Box` peut contenir plusieurs éléments graphiques, disposés horizontalement ou verticalement. On pourrait créer des agencements plus complexes en mettant plusieurs boîtes dans une autre et ainsi de suite.

Il existe un concepteur graphique d'interface utilisateur appelé Glade intégré à Anjuta ce qui rend la conception d'interface utilisateur vraiment facile. Dans cet exemple simple, cependant, nous allons tout programmer à la main.

Ajoutons la boîte et les éléments graphiques à la fenêtre. Insérez le code suivant dans la méthode `_init` immédiatement au-dessus de la ligne `this.window.show` :

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

La première ligne crée une boîte `Gtk.Box` appelée `main_box` et définit deux de ses propriétés : l'`orientation` est fixée à verticale (donc les éléments graphiques sont disposés en colonne) et l'espacement `spacing` entre les éléments graphiques est fixé à 0 pixel. La ligne suivante ajoute cette nouvelle boîte `Gtk.Box` à la fenêtre.

Pour l'instant, la fenêtre ne contient qu'une boîte `Gtk.Box` vide et si vous exécutez le programme, vous ne verrez pas encore de changement (la boîte `Gtk.Box` est un conteneur transparent et vous ne le voyez donc pas).

# Placement : ajout d'éléments graphiques au conteneur

Pour ajouter des éléments graphiques à la boîte `Gtk.Box`, insérez le code suivant juste en dessous de la ligne `this.window.add (main_box)` :

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

La première ligne crée une nouvelle `Gtk.Image` appelée `image` qui servira à afficher un fichier image. Puis, l'élément graphique image est ajouté (placé) dans le conteneur `main_box` par la méthode `pack_start` de `Gtk.Box` .

`pack_start` prend 4 arguments : l'élément graphique enfant (`child`) qui doit être ajouté à la boîte `Gtk.Box` ; si la boîte `Gtk.Box` doit s'agrandir (`expand`) quand le nouvel élément graphique est ajouté ; si le nouvel élément graphique doit prendre tout le nouvel espace créé quand la boîte `Gtk.Box` s'agrandit (`fill`) ; et enfin combien d'espace libre (`padding`), en pixels, il doit y avoir entre l'élément graphique et ses voisins à l'intérieur de la `Gtk.Box`.

Si vous les laissez faire, les conteneurs Gtk (et les éléments graphiques) s'agrandissent dynamiquement pour occuper tout l'espace disponible. Vous ne positionnez pas les éléments graphiques dans la fenêtre en leur spécifiant des coordonnées x,y précises mais vous les positionnez les uns par rapport aux autres. Ceci permet un redimensionnement plus aisé de la fenêtre et les éléments graphiques devraient automatiquement prendre une taille raisonnable dans la plupart des cas.

Notez aussi de quelle manière les éléments graphiques sont organisés hiérarchiquement. Une fois placée dans la `Gtk.Box`, l'image `Gtk.Image` est considérée comme un enfant de la boîte `Gtk.Box`. Ceci vous permet de traiter tous les enfants d'un élément graphique comme un groupe ; par exemple, vous pouvez masquer la boîte `Gtk.Box` qui du coup, masque tous ses enfants en même temps.

Insérez maintenant ces deux lignes en dessous des deux que vous venez d'ajouter :

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

Ces lignes ressemblent aux deux premières, mais cette fois elles créent un bouton `Gtk.Button` et l'ajoute à la `main_box`. Notez que nous paramétrons ici l'argument `expand` (le second) sur `false`, alors qu'il était sur `true` pour l'image `Gtk.Image`. Ceci va conduire à ce que l'image prenne tout l'espace disponible et le bouton seulement l'espace nécessaire. Lors d'un redimensionnement de la fenêtre, la taille du bouton reste identique, alors que la taille de l'image va augmenter pour occuper le reste de la fenêtre.

Finalement, nous devons modifier la ligne `this.window.show ();` pour devenir :

this.window.show_all ();

Ceci affiche l'enfant de la fenêtre Gtk et tous ses enfants, enfants de ses enfants et ainsi de suite (souvenez-vous que les éléments graphiques Gtk sont tous masqués par défaut).

# Chargement de l'image : connexion au signal `clicked` du bouton

Quand l'utilisateur clique sur le bouton Open a picture, une boîte de dialogue devrait apparaître pour permettre le choix d'une image. Une fois ce choix effectué, la photo est chargée et affichée dans l'élément graphique image.

Connectez d'abord le signal `clicked` du bouton à une fonction de gestion de signal que vous appelez `_openClicked`. Mettez ce code immédiatement après la ligne `var open_button = new Gtk.Button` où le bouton a été créé :

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

Ici, nous utilisons l'assistant JavaScript Lang. Il nous permet de connecter une class method au signal plutôt qu'à une simple fonction (sans classe) que nous avions utilisée avant pour le signal de masquage `hide`. Ne vous préoccupez pas de cela pour le moment, ce n'est qu'un détail technique. Pour que cela fonctionne, vous devez aussi ajouter cette ligne en haut du fichier :

const Lang = imports.lang;

# Chargement de l'image : écriture de la fonction de rappel du signal

Nous pouvons maintenant créer la méthode `_openClicked()`. Insérez ce qui suit dans le bloc de code `ImageViewer.prototype`, après la méthode `_init` (et sans oublier la virgule) :

_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 (); }

C'est un peu plus compliqué que tout ce que nous avons essayé jusqu'à présent, donc décortiquons cette partie étape par étape :

La ligne commençant par `var chooser` crée une boîte de dialogue Ouvrir qui permet à l'utilisateur de choisir des fichiers. Nous paramétrons quatre propriétés : le titre de la boîte de dialogue ; la fonction (le type) de la boîte de dialogue (c'est une boîte de dialogue « OPEN », mais on aurait pu utiliser (`SAVE`) (enregistrer) si notre intention avait été d'enregistrer un fichier) ; `transient_for`, qui définit la fenêtre parent de la boîte de dialogue ; et `modal` qui, s'il est fixé à `true` empêche l'utilisateur de cliquer sur un autre emplacement de l'application jusqu'à ce que la boîte de dialogue soit fermée.

Les deux lignes suivantes ajoutent les boutons Cancel (Annuler) et Open (Ouvrir) à la boîte de dialogue. Le second argument de la méthode `add_button` est la valeur (de type entier) qui est retournée lorsque le bouton est cliqué : 0 pour Annuler et 1 pour Ouvrir.

Notez que nous utilisons les noms de bouton de la collection (stock) Gtk au lieu de saisir manuellement « Cancel » ou « Open ». L'avantage d'utiliser les noms de la collection est que les étiquettes des boutons seront déjà traduites dans la langue de l'utilisateur.

`set_default_response` détermine le bouton qui est activé quand l'utilisateur fait un double-clic sur un fichier ou appuie sur la touche Entrée. Ici, nous utilisons le bouton Open (qui a la valeur 1).

Les trois lignes suivantes limitent la boîte de dialogue Ouvrir à l'affichage des seuls fichiers pouvant être ouverts par `Gtk.Image`. Un objet filtre est d'abord créé ; ensuite nous ajoutons tous les types de fichier pris en charge par `Gdk.Pixbuf` (ce qui inclut la plupart des formats d'image comme PNG ou JPEG) au filtre. Enfin, nous appliquons ce filtre à la boîte de dialogue Open.

`chooser.run` affiche la boîte de dialogue Open. La boîte de dialogue attend que l'utilisateur choisisse une image ; quand c'est fait, `chooser.run` retourne la valeur 1 (il retourne la valeur 0 si l'utilisateur clique sur Annuler). L'instruction `if` teste cette réponse.

Supposons que l'utilisateur a cliqué sur le bouton Ouvrir, la ligne suivante définit la propriété `file` du `Gtk.Image` au nom de fichier image sélectionné. `Gtk.Image` charge alors l'image choisie et l'affiche.

La dernière ligne de cette méthode détruit la boîte de dialogue Open car nous n'en avons plus besoin.

# Exécution de l'application

Tout le programme nécessaire est maintenant en place, donc essayez de l'exécuter. Cela devrait fonctionner ; un visionneur d'images totalement fonctionnel (et une visite éclair de JavaScript et de Gtk) en très peu de temps !

# Implémentation de référence

Si vous rencontrez des difficultés avec ce tutoriel, comparez votre programme à ce programme de référence.

# Les étapes suivantes

Voici quelques idées sur la manière d'étendre ce simple exemple :

Faire que l'utilisateur puisse sélectionner un dossier plutôt qu'un fichier et fournir les contrôles pour naviguer parmi toutes les images d'un dossier.

Appliquer au hasard des filtres et des effets à l'image quand elle est chargée et permettre à l'utilisateur d'enregistrer l'image modifiée.

GEGL fournit de puissantes possibilités de manipulation d'image.

Permettre à l'utilisateur de charger des images depuis des sites de partage, des scanners ou d'autres sources plus sophistiquées.

You can use GIO to handle network file transfers and the like, and GNOME Scan to handle scanning.