<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="photo-wall.c" xml:lang="fr">
  <info>
    <title type="text">Photo Wall (C)</title>
    <link type="guide" xref="c"/>

    <desc>Un visionneur d'images avec 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 photos</title>

<synopsis>
  <p>Dans cet exemple, nous allons fabriquer un visionneur d'images simple avec Clutter. Vous apprendrez :</p>
  <list>
    <item><p>comment dimensionner et positionner les <code>ClutterActor</code>,</p></item>
    <item><p>comment placer une image dans un <code>ClutterActor</code>,</p></item>
    <item><p>comment faire des transitions simples avec la structure d'animation de Clutter,</p></item>
    <item><p>comment faire réagir les <code>ClutterActor</code> aux événements de la souris,</p></item>
    <item><p>et comment récupérer des noms de fichier depuis un répertoire.</p></item>
  </list>
</synopsis>

<section id="intro">
  <title>Introduction</title>
  <p>Clutter est une bibliothèque pour créer des interfaces utilisateur dynamiques utilisant OpenGL pour l'accélération matérielle. Cet exemple montre une petite partie, mais néanmoins centrale, de la bibliothèque Clutter pour écrire un programme simple, mais sympathique, de visionneur d'images.</p>
  <p>Pour nous aider dans cette tâche, nous utilisons également quelques autres éléments classiques de GLib. Parmi les plus importants, nous utiliserons <code>GSList</code>, une liste simplement chaînée, pour contenir nos <code>ClutterActor</code> et une autre pour les noms de chemin des fichiers. Nous utiliserons également <code>GDir</code>, un utilitaire pour travailler avec des répertoires, afin d'accéder au répertoire de nos images et de récupérer les chemins de fichier.</p>
</section>

<section id="anjuta">
  <title>Création d'un projet dans Anjuta</title>
  <p>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.</p>
  <steps>
    <item>
    <p>Lancez Anjuta et cliquez sur <guiseq><gui>Fichier</gui><gui>Nouveau</gui><gui>Projet</gui></guiseq> pour ouvrir l'assistant de création de projet.</p>
    </item>
    <item>
    <p>Cliquez sur l'onglet <gui>C</gui>, choisissez <gui>Gtk+ (simple)</gui>, cliquez sur <gui>Continuer</gui> et renseignez les champs requis des pages suivantes avec vos informations. Saisissez <file>murdephotos</file> (sans accent) comme nom de projet et de répertoire.</p>
   	</item>
    <item>
    <p>Assurez-vous d'avoir désactivé <gui>Utiliser GtkBuilder pour l'interface utilisateur</gui> car nous allons créer l'interface utilisateur manuellement dans cet exemple. Consultez le tutoriel <link xref="guitar-tuner.c">Accordeur de guitare</link> si vous souhaitez savoir comment utiliser le constructeur d'interface GtkBuilder.</p>
    </item>
    <item>
    <p>Activez <gui>Configuration des paquets externes</gui>. Sur la page suivante, sélectionnez <em>clutter-1.0</em> dans la liste pour inclure la bibliothèque Clutter à votre projet.</p>
    </item>
    <item>
    <p>Cliquez sur <gui>Appliquer</gui> et votre projet est créé. Ouvrez <file>src/main.c</file> depuis l'onglet <gui>Projet</gui> ou l'onglet <gui>Fichiers</gui>. Vous devez voir apparaître du code commençant par les lignes :</p>
    <code mime="text/x-csrc"><![CDATA[
#include <config.h>
#include <gtk/gtk.h>]]></code>
    </item>
  </steps>
</section>

<section id="look">
  <title>Un aperçu du mur de photos</title>
  <p>Notre visionneur d'images vous montre un mur de photos.</p>
  <media type="image" mime="image/png" src="media/photo-wall.png"/>
  <p>Quand une image est cliquée, elle est animée pour remplir la zone d'affichage. Lorsque la photo qui possède le focus est cliquée, elle retourne à sa position d'origine en utilisant une animation qui dure également 500 millisecondes.</p>
  <media type="image" mime="image/png" src="media/photo-wall-focused.png"/>
</section>

<section id="setup">
  <title>Configuration initiale</title>
  <p>La partie de code suivante contient beaucoup de définitions et de variables qui sont utilisées dans les sections suivantes. Servez-vous en comme référence. Copiez ce code au début du fichier <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>Immersion dans le code</title>
  <p>Nous commencerons par analyser la fonction <code>main()</code> dans son ensemble. Ensuite nous discuterons des autres parties du programme en détail. Modifiez le fichier <file>src/main.c</file> pour qu'il contienne la fonction <code>main()</code>. Vous pouvez aussi supprimer la fonction <code>create_window()</code> car on n'en a plus besoin dans cet 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>Ligne 4 : configuration de <code>ClutterColor</code> en paramétrant les valeurs rouge, vert, bleu et celle de transparence (alpha). Les valeurs sont comprises entre 0 et 255. Pour la transparence, une valeur de 255 représente l'opacité.</p></item>
    <item><p>Ligne 7 : vous devez initialiser Clutter. Attention, si vous oubliez de le faire, vous aurez de très étranges messages d'erreur. Vous êtes prévenu.</p></item>
    <item><p>Lignes 9‒11 : ici nous obtenons le <code>ClutterStage</code> par défaut qui a été fourni par <code>clutter_init</code> puis nous définissons sa taille en utilisant les variables définies à la section précédente et l'adresse du <code>ClutterColor</code> que nous venons de définir.</p>
      <note><p>Un <code>ClutterStage</code> est le <code>ClutterActor</code> de premier niveau sur lequel les autres <code>ClutterActor</code> sont disposés.</p></note>
</item>
    <item><p>Ligne 13 : ici nous appelons notre fonction pour obtenir les chemins des fichiers image. Nous l'examinerons dans un instant.</p></item>
    <item><p>Ligne 15-27 : c'est l'endroit où nous paramétrons les <code>ClutterActor</code>, chargeons les images et les disposons au bon endroit dans le mur d'images. Nous regarderons cela en détail dans la section suivante.</p></item>
    <item><p>Ligne 29 : affichage de « stage » et de <em>tous ses enfants</em>, c'est-à-dire nos images.</p></item>
    <item><p>Ligne 32 : démarrage de la boucle principale de Clutter.</p></item>
  </list>
</section>

<section id="actors">
  <title>Mise en place de nos acteurs image</title>
 <note><p>Dans Clutter, un acteur est l'élément visuel le plus élémentaire. En gros, tout ce que vous voyez est un acteur.</p></note>
<p>Dans cette section, nous allons regarder plus en détail la boucle utilisée pour paramétrer les <code>ClutterActor</code> qui affichent nos images.</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>Ligne 5 : ici nous voulons obtenir le chemin à la <var>n</var>ième position de la <code>GSList</code> qui contient les noms de chemin de nos images. La <var>n</var>ième position est calculée à partir de <code>row</code> et <code>col</code>. La valeur retournée est un pointeur vers une <code>GSList</code> qui est juste un nœud dans la liste. Nous l'utiliserons dans la ligne suivante pour obtenir le chemin réel. Le premier argument est un pointeur vers le début de la liste.</p>
  </item>
  <item><p>Ligne 6 : c'est ici que nous créons réellement le <code>ClutterActor</code> et disposons l'image dans l'acteur. Le premier argument est le chemin qui permet d'accéder au nœud de notre <code>GSList</code>. Le deuxième sert à rapporter une erreur mais nous allons ignorer cela pour faire court.</p>
  </item>
  <item><p>Ligne 7 : nous regarderons cette fonction dans une section ultérieure.</p>
  </item>
  <item><p>Ligne 8 : cela ajoute le <code>ClutterActor</code> au « stage », qui est un conteneur. Cela suppose une notion d'appartenance du <code>ClutterActor</code> qui est quelque chose que vous devrez comprendre lorsque vous irez un peu plus loin dans le développement de GNOME. Consultez la <link href="http://library.gnome.org/devel/gobject/stable/gobject-memory.html">documentation de <code>GObject</code></link> pour des détails pointus.</p>
  </item>
  <item><p>Ligne 9 : cela ajoute notre <code>ClutterActor</code> à une <code>GSList</code> afin que nous puissions plus tard itérer sur les <code>ClutterActor</code>.</p>
<note><p>Il est intéressant de noter que nous ajoutons les <code>ClutterActor</code> en tête de liste plutôt qu'en fin de liste afin d'éviter d'avoir à parcourir la liste à chaque insertion. Vous verrez souvent <code>g_slist_prepend</code> suivi de <code>g_slist_reverse</code> car c'est plus rapide que d'insérer beaucoup d'objets à la fin de la liste.</p></note>
  </item>
</list>
</section>

<section id="load">
  <title>Chargement des images</title>
  <p>Oublions un court instant Clutter pour regarder comment nous pouvons obtenir les noms des fichiers contenus dans notre répertoire d'images.</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>Lignes 5 et 12 : cela ouvre notre répertoire ou, en cas d'erreur, quitte la fonction après affichage d'un message d'erreur.</p></item>
    <item><p>Ligne 14-23 : la première ligne récupère un nouveau nom de fichier à partir du <code>GDir</code> que nous avons ouvert précédemment. S'il existe des fichiers images (ce que nous vérifions en examinant son extension, « .png » ou « .jpg ») dans le répertoire, nous continuons en ajoutant le chemin du répertoire de l'image devant le nom de fichier puis en l'ajoutant en tête de la liste définie auparavant. Enfin, nous essayons d'obtenir le prochain nom de fichier et nous recommençons la boucle si un autre fichier a été trouvé.</p></item>
  </list>
</section>

<section id="actors2">
  <title>Mise en place des acteurs</title>
  <p>Examinons maintenant le choix de la taille et du positionnement des <code>ClutterActor</code> et également la préparation du <code>ClutterActor</code> pour une interaction de l'utilisateur.</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>Ligne 7 : le fait de définir un acteur comme « reactive » signifie qu'il réagit aux événements, au <code>button-press-event</code> dans notre cas. Pour le mur de photos, tous les <code>ClutterActor</code> du mur doivent être initialisés comme « reactive ».</p>
    </item>
    <item>
      <p>Ligne 9-12 : nous connectons maintenant l'événement <code>button-press-event</code> à la fonction de rappel <code>actor_clicked_cb</code> que nous examinons ci-dessous.</p>
    </item>
  </list>
  <p>À cet instant, nous obtenons un mur d'images qui sont prêtes à être regardées.</p>
</section>

<section id="click">
  <title>Réaction aux 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>Ligne 1-4 : nous devons être sûr que notre fonction de rappel correspond à la signature requise par notre signal <code>button_clicked_event</code>. Dans notre exemple, nous n'utilisons que le premier argument, le <code>ClutterActor</code> qui est réellement cliqué.</p>
<note>
  <p>Quelques mots sur les arguments que nous n'utilisons pas dans cet exemple. L'événement <code>ClutterEvent</code> est différent en fonction de l'événement géré. Par exemple, un événement appui sur une touche du clavier produit un <code>ClutterKeyEvent</code> à partir duquel vous pouvez obtenir comme information, entre autres, la touche qui a été enfoncée. Pour un événement clic de souris, vous obtenez un <code>ClutterButtonEvent</code> à partir duquel vous pouvez connaître les valeurs <code>x</code> et <code>y</code>. Consultez la documentation de Clutter pour les autres types d'événement <code>ClutterEvent</code>.</p>
  <p><code>user_data</code> est ce qui sert à transmettre des données dans la fonction. Un pointeur vers n'importe quel type de données peut être transmis. Si vous avez besoin de transmettre plusieurs données à la fonction de rappel, vous pouvez mettre les données dans une structure et transmettre son adresse.</p>
</note></item>
    <item><p>Ligne 7 : nous définissons un drapeau de type « static » pour enregistrer l'état dans lequel nous sommes : en mode mur ou en mode focus. Nous commençons en mode mur donc aucune image ne possède le focus, par conséquent, nous paramétrons le drapeau à <code>FALSE</code> (FAUX) au départ.</p></item>
    <item><p>Ligne 9 : cette ligne de code exécute une fonction personnalisée <code>foreach_set_focus_state</code>, pour chaque élément de notre <code>actor_list</code>, en lui transmettant l'adresse du drapeau <code>is_focused</code>. Nous verrons la définition de la fonction <code>foreach_set_focus_state</code> dans la prochaine section.</p></item>
    <item><p>Ligne 13-19 : ces lignes sont atteintes lorsqu'une image possède actuellement le focus et que nous voulons retourner en mode mur. La fonction <code>clutter_actor_animate</code> est utilisée pour animer une ou des propriétés d'un <code>ClutterActor</code> à partir du ou des états actuels vers les états spécifiés. Les arguments sont les suivants :</p>
<list type="numbered">
  <item><p>L'adresse du <code>ClutterActor</code> à animer</p></item>
  <item><p>Le mode d'animation à utiliser. Ici nous utilisons <code>CLUTTER_LINEAR</code> pour avoir une vitesse d'animation constante.</p></item>
  <item><p>La durée de l'animation en millisecondes. J'ai choisi 500 ms pour cet exemple.</p></item>
  <item><p>Les arguments restants sont des paires propriété/valeur. Ici nous voulons définir la valeur <code>x</code> à la valeur <code>x</code> initiale, où ce <code>ClutterActor</code> était avant de posséder le focus.</p></item>
  <item><p>Le dernier argument doit toujours être <code>NULL</code> pour indiquer qu'il n'y a plus de propriétés à définir.</p></item>
</list>
<note><p>La propriété <code>depth</code> nécessite un peu plus d'explications. Nous avons besoin de mettre au premier plan l'image qui possède le focus afin qu'elle ne glisse pas derrière d'autres <code>ClutterActor</code>. Dans cette section, nous réajustons sa propriété à la même altitude que les autres images sur le mur.</p>
<p>« Depth » détermine aussi quels <code>ClutterActor</code> reçoivent les événements. Un <code>ClutterActor</code> avec une altitude plus grande reçoit les événements de clic et peut choisir si l'événement est transmis au <code>ClutterActor</code> en dessous de lui. Nous verrons comment cela fonctionne un peu plus loin.</p></note>
    </item>
    <item><p>Ligne 24 : ces lignes sont atteintes lorsque nous sommes actuellement dans l'état mur et que nous allons donner le focus à un <code>ClutterActor</code>. Ici nous enregistrons la position de départ afin de pouvoir le repositionner plus tard.</p></item>
    <item><p>Ligne 25 : le fait de paramétrer la propriété <code>reactive</code> du <code>ClutterActor</code> à <code>TRUE</code> rend ce <code>ClutterActor</code> réactif aux événements. Dans cet état de focus, le seul <code>ClutterActor</code> qui doit recevoir des événements est le <code>ClutterActor</code> qui est actuellement affiché. Un clic sur ce <code>ClutterActor</code> le repositionne à sa position de départ.</p></item>
    <item><p>Ligne 27-33 : similaire au bloc de code ci-dessus. Notez que nous paramétrons l'altitude afin de placer l'acteur devant les autres images.</p></item>
    <item><p>Ligne 37 : ici nous basculons le drapeau <code>is_focused</code> vers l'état actuel.</p></item>
<item><p>Comme mentionné ci-dessus, les <code>ClutterActor</code> qui possèdent des valeurs <code>depth</code> plus grandes reçoivent les événements mais peuvent autoriser les <code>ClutterActor</code> en dessous d'eux à recevoir les événements également. En renvoyant <code>TRUE</code>, l'acteur empêche la transmission des événements alors qu'en renvoyant <code>FALSE</code> la transmission se fait.</p>
 <note>
   <p>Rappelez-vous cependant que pour recevoir des événements les <code>ClutterActor</code> doivent être définis à <code>reactive</code>.</p>
 </note>
</item>
 </list>
 <p>Ce qui suit est la fonction bien commode transmise à <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>Ligne 2-5 : la signature de cette fonction nécessite deux <code>gpointer</code>. Le premier est un pointeur vers le <code>ClutterActor</code> que notre <code>GSList</code> contient et l'autre est le drapeau <code>is_focused</code> que nous avons transmis dans la section précédente. Nous allons en garder une trace et les enregistrer pour pouvoir les utiliser facilement.</p></item>
  <item><p>Ligne 7 : en fonction de la valeur booléenne transmise, le <code>ClutterActor</code> est paramétré pour répondre aux événements ou pas.</p></item>
</list>
</section>

<section id="run">
  <title>Construction et lancement de l'application</title>
  <p>Le programme complet devrait maintenant être prêt à fonctionner. Tout ce dont vous avez besoin est de quelques images à charger. Par défaut, les images sont chargées à partir d'un répertoire <file>berlin_images</file>. Vous pouvez, si vous voulez, modifier la ligne <code>#define IMAGE_DIR_PATH</code> qui se trouve au début du fichier pour faire référence à votre répertoire de photos ou créer un répertoire <file>berlin_images</file> en cliquant sur <guiseq><gui>Projet</gui><gui>Nouveau répertoire...</gui></guiseq> et en créant un sous-répertoire <file>berlin_images</file> dans le répertoire <file>murdephotos</file>. Assurez-vous de mettre au moins 12 images dans le répertoire !</p>
  <p>Après avoir fait cela, cliquez sur <guiseq><gui>Construire</gui><gui>Construire le projet</gui></guiseq> pour tout reconstruire, puis sur <guiseq><gui>Exécuter</gui><gui>Exécuter</gui></guiseq> pour lancer l'application.</p>
  <p>Si vous ne l'avez pas déjà fait, choisissez l'application <file>Debug/src/murdephotos</file> dans la boîte de dialogue qui apparaît. Enfin, cliquez sur <gui>Lancer</gui> et amusez-vous !</p>
</section>

<section id="impl">
 <title>Implémentation de référence</title>
 <p>Si vous rencontrez des difficultés avec ce tutoriel, comparez votre programme à ce <link href="photo-wall/photo-wall.c">programme de référence</link>.</p>
</section>

</page>
