<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="photo-wall.c" xml:lang="ca">
  <info>
    <link type="guide" xref="index#c"/>

    <desc>Un visualitzador d'imatges fet amb Clutter</desc>

    <revision pkgversion="0.1" version="0.1" date="2011-03-22" status="review"/>
    <credit type="author">
      <name>Chris Kühl</name>
      <email>chrisk@openismus.com</email>
    </credit>
    <credit type="author">
      <name>Johannes Schmid</name>
      <email>jhs@gnome.org</email>
    </credit>
  </info>

<title>Mur de fotografies</title>

<synopsis>
  <p>En aquest exemple es construirà un visualitzador d'imatges senzill amb la Clutter. Aprendreu a:</p>
  <list>
    <item><p>Com dimensionar i posicionar els <code>ClutterActor</code></p></item>
    <item><p>Com posar una imatge en un <code>ClutterActor</code></p></item>
    <item><p>Com fer transicions senzilles utilitzant l'entorn de treball d'animacions de la Clutter</p></item>
    <item><p>Com fer que els <code>ClutterActor</code> responguin a esdeveniments del ratolí</p></item>
    <item><p>Com obtenir els noms dels fitxers d'un directori</p></item>
  </list>
</synopsis>

<section id="intro">
  <title>Introducció</title>
  <p>La Clutter és una biblioteca per crear interfícies d'usuari dinàmiques amb OpenGL per beneficiar-se de l'acceleració per maquinari. Aquest exemple mostra una petita, però important, part de la biblioteca Clutter per crear un visualitzador d'imatges simple però atractiu.</p>
  <p>Per facilitar l'obtenció del nostre objectiu també s'utilitzaran algunes parts comunes de la GLib. Principalment utilitzarem una <code>GSList</code>, una llista enllaçada simple, per contenir els <code>ClutterActor</code> i una altra llista pels camins dels fitxers. També utilitzarem la <code>GDir</code>, una utilitat per treballar amb directoris, per accedir al directori d'imatges de l'usuari i obtenir-ne els camins dels fitxers.</p>
</section>

<section id="anjuta">
  <title>Creació d'un projecte a l'Anjuta</title>
  <p>Abans de començar a programar, heu de crear un projecte nou a l'Anjuta. L'Anjuta crearà tots els fitxers necessaris per, més endavant, construir i executar el codi. És molt útil per així mantenir-ho tot junt.</p>
  <steps>
    <item>
    <p>Inicieu l'Anjuta i feu clic a <guiseq><gui>Fitxer</gui><gui>Nou</gui><gui>Projecte</gui></guiseq> per obrir l'auxiliar de projectes.</p>
    </item>
    <item>
    <p>Choose <gui>Gtk+ (simple)</gui> from the <gui>C</gui> tab, click <gui>Continue</gui>, and fill out your details on the next few pages. Use <file>photo-wall</file> as project name and directory.</p>
   	</item>
    <item>
    <p>Assegureu-vos que <gui>Utilitza el GtkBuilder per a la interfície d'usuari</gui> està desactivat ja que en aquest programa d'aprenentatge es crearà la interfície d'usuari manualment. Feu una ullada al programa d'aprenentatge <link xref="guitar-tuner.c">Afinació de guitarres</link> que utilitza el constructor d'interfícies (GtkBuilder).</p>
    </item>
    <item>
    <p>Habiliteu <gui>Configura els paquets externs</gui>. A la llista de la pàgina següent seleccioneu <em>clutter-1.0</em> per incloure la biblioteca Clutter al projecte.</p>
    </item>
    <item>
    <p>Feu clic a <gui>Aplica</gui> i es crearà el projecte. Obriu <file>src/main.c</file> des de les pestanyes <gui>Projecte</gui> o <gui>Fitxer</gui>. Hauríeu de veure una mica de codi que comença amb les línies:</p>
    <code mime="text/x-csrc"><![CDATA[
#include <config.h>
#include <gtk/gtk.h>]]></code>
    </item>
  </steps>
</section>

<section id="look">
  <title>Una mirada al Mur de Fotografies</title>
  <p>El visualitzador d'imatges mostra un mur d'imatges a l'usuari.</p>
  <media type="image" mime="image/png" src="media/photo-wall.png"/>
  <p>Quan es fa clic a una imatge, aquesta s'anima per cobrir l'àrea de visualització. Quan es fa clic a la imatge que té el focus, aquesta retorna a la seva posició original amb una animació que dura exactament 500 miŀlisegons.</p>
  <media type="image" mime="image/png" src="media/photo-wall-focused.png"/>
</section>

<section id="setup">
  <title>Configuració inicial</title>
  <p>El segment de codi que ve a continuació conté la majoria de definicions i variables que utilitzarem en les seccions següents. Podeu utilitzar-ho com a referència per a les seccions posteriors. Copieu aquest codi a l'inici de <file>src/main.c</file>:</p>
<code mime="text/x-csrc" style="numbered"><![CDATA[
#include <clutter/clutter.h>

#define STAGE_WIDTH  800
#define STAGE_HEIGHT 600

#define THUMBNAIL_SIZE 200
#define ROW_COUNT (STAGE_HEIGHT / THUMBNAIL_SIZE)
#define COL_COUNT (STAGE_WIDTH  / THUMBNAIL_SIZE)
#define THUMBNAIL_COUNT (ROW_COUNT * COL_COUNT)

#define ANIMATION_DURATION_MS 500

#define FOCUS_DEPTH 100.0
#define UNFOCUS_DEPTH 0.0

#define IMAGE_DIR_PATH "./berlin_images/"

static GSList *actor_list = NULL;
static GSList *img_path_list = NULL;

typedef struct Position
{
    float x;
    float y;
}
Position;

static Position origin = {0, 0};
]]>
</code>
</section>

<section id="code">
  <title>Primers passos en el codi</title>
  <p>Es farà primer una ullada general a la funció <code>main()</code>. Després es mirarà la resta de seccions del codi en més profunditat. Canvieu el fitxer <file>src/main.c</file> perquè contingui aquesta funció <code>main()</code>. Podeu esborrar la funció <code>create_window()</code> perquè no fa falta per aquest exemple.</p>
  <code mime="text/x-csrc" style="numbered"><![CDATA[
int
main(int argc, char *argv[])
{
    ClutterColor stage_color = { 16, 16, 16, 255 };
    ClutterActor *stage = NULL;

    clutter_init(&argc, &argv);

    stage = clutter_stage_get_default();
    clutter_actor_set_size(stage, STAGE_WIDTH, STAGE_HEIGHT);
    clutter_stage_set_color(CLUTTER_STAGE (stage), &stage_color);

    load_image_path_names();

    guint row = 0;
    guint col = 0;
    for(row=0; row < ROW_COUNT; ++row)
    {
        for(col=0; col < COL_COUNT; ++col)
        {
            GSList *img_path_node = g_slist_nth(img_path_list, (row * COL_COUNT) + col);
            ClutterActor *actor = clutter_texture_new_from_file((gchar *)(img_path_node->data), NULL);
            initialize_actor(actor, row, col);
            clutter_container_add_actor(CLUTTER_CONTAINER(stage), actor);
            actor_list = g_slist_prepend(actor_list, actor);
        }
    }

    /* Show the stage. */
    clutter_actor_show(stage);

    /* Start the clutter main loop. */
    clutter_main();

    return 0;
}]]></code>
  <list>
    <item><p>Línia 4: el <code>ClutterColor</code> es defineix establint els valors del vermell, el verd, el blau i de la transparència (alfa). El rang de valors és de 0 a 255. Per la transparència un valor de 255 és opac.</p></item>
    <item><p>Línia 7: heu d'inicialitzar la Clutter. Si us en descuideu, obtindreu errors molt estranys. Tingueu-ho en compte.</p></item>
    <item><p>Línies 9-11: aquí s'obté el <code>ClutterStage</code> genèric que proporciona el <code>clutter_init</code>. Llavors s'estableix les dimensions amb les definicions de la secció anterior i l'adreça del <code>ClutterColor</code> que s'acaba de definir.</p>
      <note><p>Un <code>ClutterStage</code> és el <code>ClutterActor</code> de més alt nivell on es posen d'altres <code>ClutterActor</code>.</p></note>
</item>
    <item><p>Línia 12: aquí es crida una funció pròpia per obtenir els camins a les imatges. Es repassarà el codi d'aquesta una mica més avall.</p></item>
    <item><p>Línies 14-26: aquí és on defineixen els <code>ClutterActor</code>, es carreguen les imatges i es coŀloquen en el seu lloc dins el mur d'imatges. En la secció següent si entrarà en més detall.</p></item>
    <item><p>Línia 29: mostra l'escenari i <em>tots els seus fills</em>, o sigui totes les imatges.</p></item>
    <item><p>Línia 32: s'inicia el bucle principal de la Clutter.</p></item>
  </list>
</section>

<section id="actors">
  <title>Configuració dels actors d'imatges</title>
 <note><p>A la Clutter un actor és l'element visual bàsic. Tot el que es veu és un actor.</p></note>
<p>En aquesta secció, es farà una repassada amb més detall al bucle que s'utilitza per definir els <code>ClutterActor</code> que mostraran les imatges.</p>
  <code mime="text/x-csrc" style="numbered"><![CDATA[
for(row=0; row < ROW_COUNT; ++row)
{
    for(col=0; col < COL_COUNT; ++col)
    {
        GSList *img_path_node = g_slist_nth(img_path_list, (row * COL_COUNT) + col);
        ClutterActor *actor = clutter_texture_new_from_file((gchar *)(img_path_node->data), NULL);
        initialize_actor(actor, row, col);
        clutter_container_add_actor(CLUTTER_CONTAINER(stage), actor);
        actor_list = g_slist_prepend(actor_list, actor);
    }
}
]]>
</code>
<list>
  <item><p>Línia 5: aquí s'obté el camí a la e<var>n</var>èsima posició de la <code>GSList</code> que conté el nom del camí a la imatge. El càlcul de la e<var>n</var>èsima posició es basa en la <code>row</code> i la <code>col</code>. El valor retornat és un punter a una <code>GSList</code>, la qual és només un node de la llista. S'utilitzarà aquest punter per obtenir el camí real en la línia següent. El primer paràmetre és un punter al capdavant de la llista.</p>
  </item>
  <item><p>Línia 6: aquí és on es crea realment el <code>ClutterActor</code> i se li assigna la imatge dins l'actor. El primer argument és el camí al qual hi ha la imatge a través del node de la <code>GSList</code>. El segon argument s'utilitza per informar sobre errades, però s'ignora per fer-ho més breu.</p>
  </item>
  <item><p>Línia 7: aquesta funció es mirarà amb més detall més endavant.</p>
  </item>
  <item><p>Línia 8: s'afegeix el <code>ClutterActor</code> a l'escenari, el qual és un contenidor. També assumeix la propietat del <code>ClutterActor</code>, aspecte que voldreu investigar a mesura que progresseu en el desenvolupament de GNOME. Mireu la <link href="http://library.gnome.org/devel/gobject/stable/gobject-memory.html">documentació del <code>GObject</code></link> pels detalls sòrdids.</p>
  </item>
  <item><p>Línia 9: s'afegeix el <code>ClutterActor</code> a una <code>GSList</code> per tal que més tard puguem iterar sobre els <code>ClutterActor</code>.</p>
<note><p>És interessant ressaltar que s'afegeixen els <code>ClutterActor</code> al principi en comptes de al final, per tal d'evitar recorre la llista en cada inserció. Veureu sovint <code>g_slist_prepend</code> seguit de <code>g_slist_reverse</code> perquè és més ràpid que inserir molts objectes al final d'una llista. </p></note>
  </item>
</list>
</section>

<section id="load">
  <title>Càrrega de les imatges</title>
  <p>Abans de continuar amb la Clutter s'explica a continuació com es poden obtenir els noms dels fitxers del directori d'imatges de l'usuari.</p>
  <code mime="text/x-csrc" style="numbered"><![CDATA[
static void
load_image_path_names()
{
    /* Ensure we can access the directory. */
    GError *error = NULL;
    GDir *dir = g_dir_open(IMAGE_DIR_PATH, 0, &error);
    if(error)
    {
        g_warning("g_dir_open() failed with error: %s\n", error->message);
        g_clear_error(&error);
        return;
    }

    const gchar *filename = g_dir_read_name(dir);
    while(filename)
    {
        if(g_str_has_suffix(filename, ".jpg") || g_str_has_suffix(filename, ".png"))
        {
            gchar *path = g_build_filename(IMAGE_DIR_PATH, filename, NULL);
            img_path_list = g_slist_prepend(img_path_list, path);
        }
        filename = g_dir_read_name(dir);
    }
}]]></code>
  <list>
    <item><p>Línies 5 i 12: s'obre el directori de l'usuari o, si es produeix un error, retorna després de mostrar un missatge d'error.</p></item>
    <item><p>Línies 14-23: la primera línia obté un altre nom de fitxer del <code>GDir</code> que s'ha obert anteriorment. Si en el directori hi ha un fitxer d'imatge (es comprova mirant l'extensió sigui «.png» o «.jpg») es concatena el camí del directori i el de la imatge i el resultat es posa al principi de la llista que s'ha establert abans. Finalment s'intenta obtenir el nom de camí següent i en cas que s'hagi trobat un fitxer es torna a entrar al bucle.</p></item>
  </list>
</section>

<section id="actors2">
  <title>Configuració dels actors</title>
  <p>En aquesta secció es descriu com dimensionar i posicionar els <code>ClutterActor</code> i com preparar-los per la interacció amb l'usuari.</p>
  <code mime="text/x-csrc" style="numbered"><![CDATA[
/* This function handles setting up and placing the rectangles. */
static void
initialize_actor(ClutterActor *actor, guint row, guint col)
{
    clutter_actor_set_size(actor, THUMBNAIL_SIZE, THUMBNAIL_SIZE);
    clutter_actor_set_position(actor, col * THUMBNAIL_SIZE, row * THUMBNAIL_SIZE);
    clutter_actor_set_reactive(actor, TRUE);

    g_signal_connect(actor,
                     "button-press-event",
                     G_CALLBACK(actor_clicked_cb),
                     NULL);
}]]></code>
  <list>
    <item>
      <p>Línia 7: establir un actor en mode reactiu significa que reaccionarà als esdeveniments, com ara el <code>button-press-event</code> de l'exemple que segueix. Pel mur de fotografies, tots els <code>ClutterActor</code> del mur s'han d'establir com a reactius inicialment.</p>
    </item>
    <item>
      <p>Línia 9 a 12: es connecta el <code>button-press-event</code> a la crida de retorn <code>actor_clicked_cb</code>, que es detallarà tot més endavant.</p>
    </item>
  </list>
  <p>En aquest moment ja s'ha obtingut un mur de fotografies a punt per visualitzar-se.</p>
</section>

<section id="click">
  <title>Reacció als clics</title>
  <p>

  </p>
  <code mime="text/x-csrc" style="numbered"><![CDATA[
static gboolean
actor_clicked_cb(ClutterActor *actor,
                 ClutterEvent *event,
                 gpointer      user_data)
{
    /* Flag to keep track of our state. */
    static gboolean is_focused = FALSE;

    g_slist_foreach(actor_list, foreach_set_focus_state, &is_focused);

    if(is_focused)
    {
        clutter_actor_animate(actor, CLUTTER_LINEAR, ANIMATION_DURATION_MS,
                              "x",      origin.x,
                              "y",      origin.y,
                              "depth",  UNFOCUS_DEPTH,
                              "width",  (float) THUMBNAIL_SIZE,
                              "height", (float) THUMBNAIL_SIZE,
                              NULL);
    }
    else
    {
        /*Save the current location before animating. */
        clutter_actor_get_position(actor, &origin.x, &origin.y);
        clutter_actor_set_reactive(actor, TRUE);
        clutter_actor_animate(actor, CLUTTER_LINEAR, ANIMATION_DURATION_MS,
                              "x",      (STAGE_WIDTH - STAGE_HEIGHT) / 2.0,
                              "y",      0.0,
                              "depth",  FOCUS_DEPTH,
                              "width",  (float) STAGE_HEIGHT,
                              "height", (float) STAGE_HEIGHT,
                              NULL);
    }

    /* Toggle our flag. */
    is_focused = !is_focused;

    return TRUE;
}]]></code>
  <list>
    <item><p>Línies 1 a 4: assegureu-vos que la funció de crida de retorn coincideix amb la signatura de la senyal <code>button_clicked_event</code>. A l'exemple només es fa servir el primer argument, el <code>ClutterActor</code> al que es fa clic.</p>
<note>
  <p>Un breu resum sobre els arguments que no s'utilitzen en aquest exemple. El <code>ClutterEvent</code> és diferent depenent de quin esdeveniment es gestiona. Per exemple, un esdeveniment de tecla produeix un <code>ClutterKeyEvent</code> del qual podeu obtenir la tecla premuda a més d'altra informació. Pels esdeveniments de ratolí obteniu un <code>ClutterButtonEvent</code> del qual obtindreu els valors <code>x</code> i <code>y</code>. Vegeu la documentació de la Clutter per altres tipus de <code>ClutterEvent</code>.</p>
  <p>El paràmetre <code>user_data</code> és el que es faria servir per passar dades dins la funció. S'hi pot passar un punter a qualsevol tipus de dades. Si necessiteu passar diverses dades a la crida de retorn, podeu posar les dades en una estructura i passar-ne només l'adreça. </p>
</note></item>
    <item><p>Línia 7: s'estableix un indicador estàtic per fer un seguiment de l'esta d'execució: en mode mur o en mode focus. A l'inici s'està en mode mur i per tan cap imatge té el focus. Així, s'estableix l'indicador a <code>FALSE</code>.</p></item>
    <item><p>Línia 9: en aquesta línia de codi s'executa un funció personalitzada: <code>foreach_set_focus_state</code>, per cada element de <code>actor_list</code> se li passa l'adreça de l'indicador <code>is_focused</code>. Veurem la definició de la funció <code>foreach_set_focus_state</code> en la següent funció.</p></item>
    <item><p>Línies 13 a 19: si s'executa aquest bloc de codi significa que una imatge té el focus i volem tornar al mode mur. La funció <code>clutter_actor_animate</code> s'utilitza per animar una o diverses propietats del <code>ClutterActor</code> de l'estat en que es troben a l'estat que s'especifica. Els arguments són els següents:</p>
<list type="numbered">
  <item><p>L'adreça del <code>ClutterActor</code> que s'animarà</p></item>
  <item><p>El mode d'animació que s'utilitzarà. En l'exemple s'utilitza el mode <code>CLUTTER_LINEAR</code> per tal de realitzar una animació a velocitat constant.</p></item>
  <item><p>La durada de l'animació en miŀlisegons. S'ha escollit 500 ms per aquest exemple.</p></item>
  <item><p>La resta d'arguments són parelles propietat/valor. S'estableix el valor de <code>x</code> al valor inicial que tenia el <code>ClutterActor</code> abans de tenir el focus.</p></item>
  <item><p>L'últim argument ha de ser sempre <code>NULL</code> per indicar que no es vol canviar cap més propietat.</p></item>
</list>
<note><p>La propietat <code>depth</code> requereix un mica més d'explicació. S'ha de destacar la imatge que té el focus de manera que no quedi darrera d'altres <code>ClutterActor</code>. En aquesta secció se li estableix la mateixa profunditat que les altres imatges en el mur.</p>
<p>La profunditat també determina quins <code>ClutterActor</code> reben esdeveniments. Un <code>ClutterActor</code> amb un valor de profunditat més alt rep els esdeveniments de clic i pot escollir si l'esdeveniment s'envia als <code>ClutterActor</code> que estan sota seu. Una mica més avall se'n mostra un exemple.</p></note>
    </item>
    <item><p>Línia 24: si s'arriba a aquesta línia de codi és que ens l'aplicació està en l'estat de mur i s'ha de donar el focus a un <code>ClutterActor</code>. Es desa la posició inicial per poder tornar-hi més endavant.</p></item>
    <item><p>Línia 25: s'estableix la propietat <code>reactive</code> del <code>ClutterActor</code> a <code>TRUE</code> permetent que reaccioni als esdeveniments. En el mode focus l'únic <code>ClutterActor</code> que ha de rebre esdeveniments és el <code>ClutterActor</code> que es visualitza. Fent-li clic tornarà a la seva posició inicial.</p></item>
    <item><p>Línies 27 a 33: és semblant al bloc de codi anterior. Noteu que s'estableix la profunditat per elevar-lo per sobre les altres imatges.</p></item>
    <item><p>Línia 37: es canvia l'indicador <code>is_focused</code> a l'estat actual.</p></item>
<item><p>Com s'ha comentat més amunt, els <code>ClutterActor</code> amb el valor de <code>depth</code> més alt rebran els esdeveniments però poden passar-lo als <code>ClutterActor</code> de sota seu. Si retorna <code>TRUE</code> no es passarà l'esdeveniment als <code>ClutterActor</code> de sota, mentre que si es retorna <code>FALSE</code> es passarà.</p>
 <note>
   <p>Recordeu, però, que per rebre esdeveniments els <code>ClutterActor</code> s'han d'establir com a <code>reactive</code>.</p>
 </note>
</item>
 </list>
 <p>El codi següent és la funció de conveniència que es passa a <code>g_slist_foreach</code>.</p>
 <code mime="text/x-csrc" style="numbered"><![CDATA[
static void
foreach_set_focus_state(gpointer data, gpointer user_data)
{
    ClutterActor *actor = CLUTTER_ACTOR(data);
    gboolean is_reactive = *((gboolean*)user_data);

    clutter_actor_set_reactive(actor, is_reactive);
}]]></code>
<list>
  <item><p>Línies 2 a 5: la signatura d'aquesta funció requereix dos <code>gpointer</code>. El primer és un punter al <code>ClutterActor</code> que està desat a la <code>GSList</code> i l'altre és l'indicador <code>is_focused</code> que s'ha establert en la secció anterior. S'han d'adaptar i desar-los per facilitar-ne el seu ús posterior.</p></item>
  <item><p>Línia 7: segons el valor booleà que es rebi com a paràmetre, s'establirà si el <code>ClutterActor</code> ha de respondre a esdeveniments.</p></item>
</list>
</section>

<section id="run">
  <title>Muntatge i execució de l'aplicació</title>
  <p>Tot el codi hauria d'estar llest per funcionar. Només fan falta les imatges per carregar. Per defecte, les imatges es carreguen des del directori <file>berlin_images</file>. Si voleu, podeu canviar-lo a línia <code>#define IMAGE_DIR_PATH</code> que està al principi del fitxer perquè apunti al directori de fotos de l'usuari, o podeu crear un directori <file>berlin_images</file> fent clic a <gui>Projecte</gui><gui>Directori nou...</gui></p>
  <p>Un cop ho hàgiu fet, feu clic a <guiseq><gui>Munta</gui><gui>Munta el projecte</gui></guiseq> per tornar-ho a muntar tot, llavors seleccioneu <guiseq><gui>Executa</gui><gui>Executa</gui></guiseq> per iniciar l'aplicació.</p>
  <p>Si encara no ho heu fet, seleccioneu l'aplicació <file>Debug/src/photo-wall</file> en el diàleg que apareix. Per acabar, premeu <gui>Executa</gui> i ja podreu provar l'aplicació.</p>
</section>

<section id="impl">
 <title>Implementació de referència</title>
 <p>Si teniu algun problema amb el programa d'aprenentatge, compareu el codi amb el <link href="photo-wall/photo-wall.c">codi de referència</link>.</p>
</section>

</page>
