<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="image-viewer.js" xml:lang="gl">

  <info>

  <title type="text">Image viewer (JavaScript)</title>

    <link type="guide" xref="js#examples"/>

    <desc>A little bit more than a simple "Hello world" application - write an image viewer in GTK+. Includes an introduction to the JavaScript language.</desc>

    <revision pkgversion="0.1" version="0.1" date="2011-03-19" status="review"/>

    <credit type="author">

      <name>Jonh Wendell</name>

      <email its:translate="no">jwendell@gnome.org</email>

    </credit>

    <credit type="author">

      <name>Johannes Schmid</name>

      <email its:translate="no">jhs@gnome.org</email>

    </credit>

    <credit type="editor">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasettii@gmail.com</email>

      <years>2013</years>

    </credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Fran Dieguez</mal:name>

      <mal:email>frandieguez@gnome.org</mal:email>

      <mal:years>2012-2013.</mal:years>

    </mal:credit>

  </info>

<title>Image viewer</title>

<synopsis>

  
Neste titorial, imos escribir un aplicativo GTK moi sinxelo que carga e mostra un ficheiro de imaxe. Vostede aprenderá a:

  <list>

    <item>
Escribir unha interface de usuario GTK básica en JavaScript
</item>

    <item>
Xestionar eventos conectando sinais a xestores de sinais
</item>

    <item>
Dispoñer interfaces de usuario GTK usando contedores
</item>

    <item>
Cargar e mostrar ficheiros de imaxe
</item>

  </list>

  
You'll need the following to be able to follow this tutorial:

  <list>

    <item>
An installed copy of the <link xref="getting-ready">Anjuta IDE</link>
</item>

    <item>
Unha copia instalada do intérprete gjs
</item>

    <item>
Coñecemento básico dunha linguaxe de programación orientada a obxectos
</item>

  </list>

</synopsis>

<media type="image" mime="image/png" src="media/image-viewer.png"/>

<section id="anjuta">

  <title>Cree un proxecto de Anjuta</title>

  
Antes de comezar a programar, deberá configurar un proxecto novo en Anjuta. Isto creará todos os ficheiros que precise para construír e executar o código máis adiante. Tamén é útil para manter todo ordenado.

  <steps>

    <item>

    
Inicie Anjuta e prema <guiseq><gui>Ficheiro</gui><gui>Novo</gui><gui>Proxecto</gui></guiseq> para abrir o asistente de proxectos.

    </item>

    <item>

    
Seleccione <gui>JavaScript xenérico</gui> desde a lapela <gui>JS</gui>, prema <gui>Adiante</gui> e complete os seus detalles nas seguintes páxinas. Use <file>image-viewer</file> como nome do proxecto e cartafol.

   	</item>

    <item>

    
Prema <gui>Aplicar</gui> e o proxecto será creado. Abra <file>src/main.js</file> desde a lapela <gui>Proxecto</gui> ou <gui>Ficheiros</gui>. Contén código de exemplo moi básico.

    </item>

  </steps>

</section>

<section id="js">

  <title>Primeiros pasos en JavaScript: Ola mundo</title>

  
Antes de comezar a escribir o visor de imaxes faremos unha introdución á forma na que JavaScript se usa en GNOME. Por suposto, o primeiro contacto con calquera linguaxe de programación debería ser un programa Ola Mundo que pode atopar <file>main.js</file>:

  print ("Ola mundo!");

  
Isto debería ser natural se está familiarizado con calquera outra linguaxe de programación. A función printi chámase co argumento «Ola Mundo», que se imprimirá en pantalla. Teña en conta que cada liña de código remata con un punto e coma.

</section>

<section id="classes">

  <title>Clases en JavaScript</title>

  
Esta é a forma estándar de definir unha clase 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);

  }

}]]>

  
Isto define unha clase chamada MyClass. Vexa cada unha das partes da definición da clase:

  <steps>

    <item>

    
function MyClass is the constructor of the class — its name must match the class's name. You can access any member of the class by using the this object; here, the constructor calls the class's _init method.

    </item>

    <item>

    
The MyClass.prototype block is where you define the structure of the class. Each class is made up of methods (functions) and fields (variables); there are three methods and two fields in this example.

    </item>

    <item>

    
The first method defined here is called _init, and we specify that it is a function with no arguments:

    _init: function ()

    
We write the function inside some curly braces. Two fields are defined here, propertyA and propertyB. The first is set to a string and the second is set to an integer (10). The function doesn't return any value.

    </item>

    <item>

    
The next method is called aMethod and has two arguments, which it prints out when you call it. The final method is dumpProperties, and prints the fields propertyA and propertyB.

    </item>

    <item>

    
Teña en conta como se ordena a definición da clase (prototipo); cada definición de función sepárase con unha coma.

    </item>

  </steps>

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

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 <file>main.js</file> and then run it by using

  <guiseq><gui>Run</gui><gui>Execute</gui></guiseq> from the menu or using the toolbar.

</section>

<section id="gtk">

  <title>Un primeiro aplicativo en GTK</title>

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

const Gtk = imports.gi.Gtk;

Gtk.init (null, null);

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

w.show ();

Gtk.main ();]]>

  
Botemos unha ollada ao que está pasando:

  <list>

    <item>

    
The first line imports the Gtk namespace (that is, it includes the Gtk library). The libraries are provided by GObject Introspection (gi), which provides language bindings for many GNOME libraries.

    </item>

    <item>

    
Gtk.init initializes the Gtk library; this statement is mandatory for all Gtk programs.

    </item>

    <item>

    
The next line creates the main window by creating a new Gtk.Window object. You can pass several properties to the window's constructor by using the syntax {property: value, property: value, ...}. In this case we are setting the title of the window.
</item>

    <item>
The next line explicitly shows the window. In Gtk, every widget is hidden by default.
</item>

    <item>
Finally, Gtk.main runs the main loop — in other words, it executes the program. The main loop listens for events (signals) from the user interface and then calls a signal handler which will do something useful. We'll learn more about signals shortly.
</item>

  </list>

  
Save the code in <file>main.js</file> 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 <keyseq><key>Ctrl</key><key>C</key></keyseq> in the terminal window to quit the program.

</section>

<section id="classes2">

  <title>Engadir clases</title>

  
The proper way of doing Gtk programming is by using classes. Let's rewrite the simple code you just wrote using 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 ();]]>

  
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.

</section>

<section id="signals">

  <title>Sinais</title>

  
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:

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.

  
A sintaxe para conectar calquera sinal a unha función é:

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

  
You can find signal definitions for any object in the <link href="https://developer.gnome.org/gtk3/stable/gtkobjects.html">GTK class reference</link>.

  <note>

    
Vostede pode simplificar o código facendo uso da definición en liña de funcións:

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

  </note>

</section>

<section id="close">

  <title>Pechar a xanela</title>

  
Ao pechar unha xanela Gtk realmente non se pecha, agóchase. Isto permítelle manter unha xanela (útil se quere preguntarlle ao usuario se realmente desexa pechar a xanela, por exemplo).

  
No noso caso, queremos pechar a xanela. A forma máis doada de facer isto é conectar o sinal hide do obxecto GtkWindow a unha función que peche o aplicativo. Vaia de novo ao ficheiro <file>image-viewer.js</file> e engada o seguinte código ao método _init, na liña superior a this.window.show.

  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.

</section>

<section id="containers2">

  <title>Contedores: deseñar a interface de usuario</title>

  
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 <link href="http://library.gnome.org/devel/gtk/stable/GtkContainer.html">container types</link> 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.

  <note>

  
There is a graphical user interface designer called <app>Glade</app> integrated in <app>Anjuta</app> which makes UI design really easy. For this simple example, however, we will code everything manually.

  </note>

  
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:

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).

</section>

<section id="packing2">

  <title>Empaquetado: Engadir widgets ao contedor</title>

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

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 <link href="http://library.gnome.org/devel/gtk/stable/GtkBox.html#gtk-box-pack-start">pack_start</link> 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.

  
Agora escriba estas dúas liñas, embaixo das dúas que acaba de engadir:

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.)

</section>

<section id="loading2">

  <title>Loading the image: Connecting to the button's clicked signal</title>

  
When the user clicks on the <gui>Open</gui> 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;

</section>

<section id="loading3">

  <title>Loading the image: Writing the signal's callback</title>

  
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):

  _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:

  <list>

    <item>

      
The line beginning with var chooser creates an <gui>Open</gui> dialog, which the user can use to choose files. We set four properties: the title of the dialog; the action (type) of the dialog (it's an "open" dialog, but we could have used SAVE if the intention was to save a file; transient_for, which sets the parent window of the dialog; and modal which, if set to true, prevents the user from clicking on another area of the application until the dialog is closed.

    </item>

    <item>

    
The next two lines add <gui>Cancel</gui> and <gui>Open</gui> buttons to the dialog. The second argument of the add_button method is the (integer) value that is returned when the button is pressed: 0 for <gui>Cancel</gui> and 1 for <gui>Open</gui>.

    
Notice that we are using stock button names from Gtk, instead of manually typing "Cancel" or "Open". The advantage of using stock names is that the button labels will already be translated into the user's language.

    </item>

    <item>

    
set_default_response determines the button that will be activated if the user double-clicks a file or presses <key>Enter</key>. In our case, we are using the <gui>Open</gui> button as default (which has the value 1).

    </item>

    <item>

    
The next three lines restrict the <gui>Open</gui> dialog to only display files which can be opened by Gtk.Image. A filter object is created first; we then add all kinds of files supported by Gdk.Pixbuf (which includes most image formats like PNG and JPEG) to the filter. Finally, we set this filter to be the <gui>Open</gui> dialog's filter.

    </item>

    <item>

    
chooser.run displays the <gui>Open</gui> dialog. The dialog will wait for the user to choose an image; when they do, chooser.run will return the value <output>1</output> (it would return <output>0</output> if the user clicked <gui>Cancel</gui>). The if statement tests for this.

    </item>

    <item>
Assuming that the user did click <gui>Open</gui>, the next line sets the file property of the Gtk.Image to the filename of the image selected by the user. The Gtk.Image will then load and display the chosen image.

    </item>

    <item>

    
In the final line of this method, we destroy the <gui>Open</gui> dialog because we don't need it any more.

    </item>

  </list>

  </section>

<section id="run">

  <title>Executar o aplicativo</title>

  
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!

</section>

<section id="impl">

 <title>Implementación de referencia</title>

 
Se ten problemas con este titorial, compare o seu código con este <link href="image-viewer/image-viewer.js">código de referencia</link>.

</section>

<section id="next">

  <title>Seguintes pasos</title>

  
Aquí hai algunhas ideas sobre como pode estender esta sinxela demostración:

  <list>

   <item>

   
Have the user select a directory rather than a file, and provide controls to cycle through all of the images in a directory.

   </item>

   <item>

   
Aplicar filtros aleatorios e efectos á imaxe cando se carga e permitir ao usuario gardar a imaxe modificada.

   
<link href="http://www.gegl.org/api.html">GEGL</link> fornece capacidades moi potentes de manipulación de imaxes.

   </item>

   <item>

   
Permitir ao usuario cargar imaxes desde recursos de rede compartidos, escáneres e outras fontes máis complicadas.

   
You can use <link href="http://library.gnome.org/devel/gio/unstable/">GIO</link> to handle network file transfers and the like, and <link href="http://library.gnome.org/devel/gnome-scan/unstable/">GNOME Scan</link> to handle scanning.

   </item>

  </list>

</section>

</page>