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

    <desc>Un visor de imágenes 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>Mural de fotos</title>

<synopsis>
  <p>Para este ejemplo se construirá un sencillo visor de imágenes usando Clutter. Aprenderá:</p>
  <list>
    <item><p>Cómo dimensionar y posicionar varios <code>ClutterActor</code></p></item>
    <item><p>Cómo situar una imagen en un <code>ClutterActor</code></p></item>
    <item><p>Cómo hacer transiciones sencillas usando el entorno de trabajo de animaciones de Clutter</p></item>
    <item><p>Cómo hacer que un <code>ClutterActor</code> responda a los eventos del ratón</p></item>
    <item><p>Cómo obtener nombres de archivos de una carpeta</p></item>
  </list>
</synopsis>

<section id="intro">
  <title>Introducción</title>
  <p>Clutter es una biblioteca para crear interfaces de usuarios dinámicas usando OpenGL para la aceleración gráfica. Este ejemplo demuestra una pequeña, pero importante parte de la biblioteca Clutter para crear un sencillo pero atractivo programa para ver imágenes.</p>
  <p>Para ayudarle a conseguir su objetivo, también se utilizarán algunos fragmentos comunes de GLib. Más importante es que se usará una <code>GSList</code>, una lista simple enlazada para tener el <code>ClutterActor</code> y otro para los nombres de las rutas de los archivos. También se usará <code>GDir</code>, una utilidad para trabajar con carpetas, acceder a nuestra carpeta de imágenes y obtener rutas de archivos.</p>
</section>

<section id="anjuta">
  <title>Crear un proyecto en Anjuta</title>
  <p>Antes de empezar a programar, deberá configurar un proyecto nuevo en Anjuta. Esto creará todos los archivos que necesite para construir y ejecutar el código más adelante. También es útil para mantener todo ordenado.</p>
  <steps>
    <item>
    <p>Inicie Anjuta y pulse <guiseq><gui>Archivo</gui><gui>Nuevo</gui><gui>Proyecto</gui></guiseq> para abrir el asistente de proyectos.</p>
    </item>
    <item>
    <p>Seleccione <gui>Gtk+ (simple)</gui> en la pestaña <gui>C</gui>, pulse <gui>Continuar</gui>, y rellene los detalles en las siguientes páginas. Use <file>mural-de-fotos</file> como nombre del proyecto y de la carpeta.</p>
   	</item>
    <item>
    <p>Asegúrese de que <gui>Usar GtkBuilder para la interfaz del usuario</gui> está desactivado, ya que, en este tutorial, la IU se creará manualmente. Revise el tutorial del <link xref="guitar-tuner.c">afinador de guitarra</link> usando el constructor de interfaces.</p>
    </item>
    <item>
    <p>Active <gui>Configurar paquetes externos</gui>. En la página siguiente, seleccione <em>clutter-1.0</em> de la lista para incluir la biblioteca Clutter en su proyecto.</p>
    </item>
    <item>
    <p>Pulse <gui>Aplicar</gui> y se creará el proyecto. Abra <file>src/main.c</file> desde las pestañas <gui>Proyecto</gui> o <gui>Archivo</gui>. Debería ver algo de código que comience con las líneas:</p>
    <code mime="text/x-csrc"><![CDATA[
#include <config.h>
#include <gtk/gtk.h>]]></code>
    </item>
  </steps>
</section>

<section id="look">
  <title>Un vistazo al mural de fotos</title>
  <p>El visor de imágenes muestra al usuario un mural de imágenes.</p>
  <media type="image" mime="image/png" src="media/photo-wall.png"/>
  <p>Cuando se pulsa una imagen, esta se anima para que rellene el área de visualización. Cuando se pulsa la imagen que tiene el foco, vuelve a su tamaño original usando una animación que dura 500 milisegundos.</p>
  <media type="image" mime="image/png" src="media/photo-wall-focused.png"/>
</section>

<section id="setup">
  <title>Configuración inicial</title>
  <p>El siguiente fragmento de código contiene muchas definiciones y variables que se usarán en las siguientes secciones. Úselo como referencia para las próximas secciones. Copie este código al principio 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>Saltar dentro del código</title>
  <p>Se empezará echando un vistazo a la función <code>main()</code> completa. Luego se verá el resto de secciones del código en detalle. Cambie el archivo <file>src/main.c</file> para que contenga la función <code>main()</code>. Puede eliminar la función <code>create_window()</code>, ya que no se usa en este ejemplo.</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ínea 4: <code>ClutterColor</code> se define configurando los valores de rojo, verde, azul y de transparencia (alfa). Los valores van de 0 a 255. Para la transparencia, el valor 255 es opaco.</p></item>
    <item><p>Línea 7: debe inicializar Clutter. Si olvida hacerlo, obtendrá mensajes muy extraños. Queda advertido.</p></item>
    <item><p>Líneas 9‒11: aquí es donde se obtiene el <code>ClutterStage</code> predeterminado que <code>clutter_init</code> proporcionó. Entonces se establece el tamaño usando el definido en la sección anterior y las direcciones del <code>ClutterColor</code> que ya están definidas.</p>
      <note><p>Un <code>ClutterStage</code> es el nivel superior de un <code>ClutterActor</code> en el que se ubican otros <code>ClutterActor</code>.</p></note>
</item>
    <item><p>Línea 12: aquí se llama a la función para obtener las rutas de las imágenes. Esto se verá en breve.</p></item>
    <item><p>Líneas 14‒26: aquí es donde se configuran los <code>ClutterActor</code>, se cargan las imágenes y se colocan en su sitio en el mural de imágenes. Esto se verá con más detalle en la siguiente sección.</p></item>
    <item><p>Línea 29: mostrar el escenario y <em>todos sus hijos</em>, es decir, las imágenes.</p></item>
    <item><p>Línea 32: iniciar el bucle principal de Clutter.</p></item>
  </list>
</section>

<section id="actors">
  <title>Configurar los actores de imagen</title>
 <note><p>En Clutter, un actor es el elemento visual más simple. Básicamente, todo lo que ve es un actor.</p></note>
<p>En esta sección, se va a mirar más detenidamente el bucle usado para configurar los <code>ClutterActor</code> que mostrarán las imágenes.</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ínea 5: aquí se quiere obtener la ruta a la ubicación <var>n</var>-ésima en la <code>GSList</code> que contiene los nombres de las rutas de las imágenes. La <var>n</var>-ésima posición se calcula basándose en <code>row</code> y <code>col</code>. El valor de retorno es un puntero a <code>GSList</code> que es simplemente un nodo en la lista. Esto se usará para obtener la ruta actual en la siguiente línea. El primer parámetro es un puntero a la cabecera de la lista.</p>
  </item>
  <item><p>Línea 6: aquí es donde actualmente se crea el <code>ClutterActor</code> y se ubica la imagen en el actor. El primer argumento es la ruta con la que se acceder al nodo de la <code>GSList</code>. El segundo argumento es para informar de un error, pero se ignora para simplificar.</p>
  </item>
  <item><p>Línea 7: está función se verá en una sección posterior.</p>
  </item>
  <item><p>Línea 8: esto añade el <code>ClutterActor</code> al escenario, que es un contenedor. Asume el propietario del <code>ClutterActor</code>, que es algo que querrá cuando profundice en el desarrollo de GNOME. Para obtener más detalles, consulte la <link href="http://library.gnome.org/devel/gobject/stable/gobject-memory.html">documentación de <code>GObject</code></link>.</p>
  </item>
  <item><p>Línea 9: esto añade el <code>ClutterActor</code> a una <code>GSList</code> por lo que luego se podrá iterar sobre los <code>ClutterActor</code>.</p>
<note><p>Es interesante tener en cuenta que se prefiere anteponer los <code>ClutterActor</code> en lugar de adjuntarlos, lo que evita atravesar la lista en cada inserción. A menudo vera <code>g_slist_prepend</code> seguido de <code>g_slist_reverse</code>, ya que es más rápido que insertar varios objetos al final de la lista.</p></note>
  </item>
</list>
</section>

<section id="load">
  <title>Cargar las imágenes</title>
  <p>Tómese un pequeño descanso de Clutter para ver cómo se pueden obtener los nombres de archivos desde la carpeta de imágenes.</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íneas 5 y 12: esto abre la carpeta o, si ocurre un error, termina después de mostrar un mensaje de error.</p></item>
    <item><p>Líneas 14‒23: la primera línea obtiene otro nombre de archivo del <code>GDir</code> abierto anteriormente. Si hay un archivo de imagen (se comprueba mirando si la extensión es «.png» o «.jpg») en la carpeta, se procede a anteponer la ruta de la carpeta de la imagen al nombre del archivo y se antepone en la lista creada anteriormente. Por último, se intenta obtener la siguiente ruta y se vuelve a entrar en el bucle si se encuentra otro archivo.</p></item>
  </list>
</section>

<section id="actors2">
  <title>Configurar los actores</title>
  <p>Eche un vistazo al tamaño y al posicionamiento de los <code>ClutterActor</code> y a cómo se deja listo el <code>ClutterActor</code> para la interacción del usuario.</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ínea 7: configurar un actor como «reactivo» significa que reacciona a los eventos tales como <code>button-press-event</code> en nuestro caso. Para el mural de fotos, todos los <code>ClutterActor</code> del mural deben ser inicialmente reactivos.</p>
    </item>
    <item>
      <p>Líneas 9‒12: ahora se conecta el evento <code>button-press-event</code> al retorno de la llamada <code>actor_clicked_cb</code> que veremos más adelante.</p>
    </item>
  </list>
  <p>En este punto tiene un mural de fotos que está listo para verse.</p>
</section>

<section id="click">
  <title>Reaccionar a las pulsaciones</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íneas 1‒4: hay que asegurarse de que la función de retorno de llamada coincide con la firma requerida para la señal <code>button_clicked_event</code>. En este ejemplo, sólo se usará el primer argumento, el <code>ClutterActor</code> pulsado actualmente.</p>
<note>
  <p>Unas pocas palabras sobre los argumentos que no se están usando en este ejemplo. El <code>ClutterEvent</code> es diferente dependiendo de qué evento se está manejando. Por ejemplo, un evento de clave produce un <code>ClutterKeyEvent</code> desde el que puede obtener la clave pulsada, entre otra información. Para eventos de pulsaciones del ratón, obtiene un <code>ClutterButtonEvent</code> con el que pueden obtener los valores <code>x</code> e <code>y</code>. Consulte la documentación de Clutter para obtener información sobre otros tipos de <code>ClutterEvent</code>.</p>
  <p>El <code>user_data</code> es lo que se usa para pasar datos a una función. Se puede pasar un puntero a cualquier tipo de estructura de datos. Si necesita pasar varios datos al retorno de la llamada, puede colocar los datos en una estructura y pasar un puntero a su dirección.</p>
</note></item>
    <item><p>Línea 7: se establece un indicador estático para seguir el estado en el que se está: modo mural o modo de foco. Se inicia en modo mural, por lo que ninguna imagen tiene el foco. Por ello, el indicador se establece inicialmente a <code>FALSE</code>.</p></item>
    <item><p>Línea 9: esta línea de código ejecuta una función personalizada, <code>foreach_set_focus_state</code>, para cada elemento de la <code>actor_list</code>, pasando la dirección al indicador <code>is_focused</code>. La definición de la función <code>foreach_set_focus_state</code> se verá en la siguiente sección.</p></item>
    <item><p>Líneas 13‒19: llegar a este código significa que actualmente sólo una imagen tiene el foco, y se quiere volver al modo mural. La función <code>clutter_actor_animate</code> se usa para animar una o varias propiedades de un <code>ClutterActor</code> desde su estado actual al estado especificado. Los argumentos son como sigue:</p>
<list type="numbered">
  <item><p>La dirección del <code>ClutterActor</code> que animar</p></item>
  <item><p>El modo de animación que usar. Aquí se ha usado <code>CLUTTER_LINEAR</code> por lo que se tiene una velocidad constante en la animación.</p></item>
  <item><p>La duración de la animación, en milisegundos. Se ha escogido 500 ms para este ejemplo.</p></item>
  <item><p>El resto de argumentos son parejas propiedad/valor. Aquí se quiere establecer el valor <code>x</code> al valor <code>x</code> inicial en el que estaba el <code>ClutterActor</code> antes de darle el foco.</p></item>
  <item><p>El último argumento debe ser siempre <code>NULL</code> para indicar que no hay más propiedades que configurar.</p></item>
</list>
<note><p>La propiedad <code>depth</code> necesita un poco más de explicación. Se debe elevar la imagen que tiene el foco para que no se deslice por debajo de otros <code>ClutterActor</code>. En esta sección se está devolviendo a la misma profundidad que las otras en el mural.</p>
<p>La profundidad también determina qué <code>ClutterActor</code> recibe eventos. Un <code>ClutterActor</code> con una profundidad alta recibe los eventos de las pulsaciones y puede elegir si el evento se envía a un <code>ClutterActor</code> que esté debajo de él. Se verá cómo funciona esto en pocos pasos.</p></note>
    </item>
    <item><p>Línea 24: llegar a esta línea de código significa que actualmente se está en el modo mural y se va a dar el foco a un <code>ClutterActor</code>. Aquí se guarda la posición inicial, por lo que se puede volver a ella más adelante.</p></item>
    <item><p>Línea 25: establecer la propiedad <code>reactive</code> del <code>ClutterActor</code> a <code>TRUE</code> hace que este <code>ClutterActor</code> reaccione a los eventos. En el estado «con foco», el único <code>ClutterActor</code> que se quiere que reciba eventos es el <code>ClutterActor</code> que se está viendo. Al pulsar sobre el <code>ClutterActor</code> volverá a su posición inicial.</p></item>
    <item><p>Líneas 27‒33: esto es similar al bloque de código anterior. Tenga en cuenta que se está estableciendo la profundidad para elevarlo por encima del resto de imágenes.</p></item>
    <item><p>Línea 37: aquí se cambia la opción <code>is_focused</code> al estado actual.</p></item>
<item><p>Como se ha mencionado anteriormente, los <code>ClutterActor</code> con valores de <code>depth</code> más altos recibirán eventos, pero pueden permitir que los <code>ClutterActor</code> que están por denajo de ellos también reciban eventos. Al devolver <code>TRUE</code> se dejarán de enviar eventos havia abajo, mientras que <code>FALSE</code> hará que los eventos pasen hacia abajo.</p>
 <note>
   <p>Recuerde, sin embargo, que para que los <code>ClutterActor</code> reciban eventos deben establecerse como <code>reactive</code>.</p>
 </note>
</item>
 </list>
 <p>Lo siguiente es la función de conveniencia pasada 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íneas 2‒5: la firma de esta función requiere dos <code>gpointer</code>. El primero es un puntero al <code>ClutterActor</code> contenido en la <code>GSList</code> y el otro es el indicador <code>is_focused</code> que se ha pasado en la sección anterior. Se quiere convertir su tipo («cast») y almacenarlos para que sea fácil usarlos.</p></item>
  <item><p>Línea 7: dependiendo de qué valor booleano se pasa, el <code>ClutterActor</code> se establecerá para que responda o no a eventos.</p></item>
</list>
</section>

<section id="run">
  <title>Construir y ejecutar la aplicación</title>
  <p>Todo el código debería estar listo para ejecutarse. Todo lo que necesita son algunas imágenes para cargar. De manera predeterminada, las imágenes se cargan desde la carpeta <file>berlin_images</file>. Si quiere, puede cambiar la línea <code>#define IMAGE_DIR_PATH</code> del principio para que haga referencia a su carpeta de fotos, o crear una carpeta <file>berlin_images</file> pulsando en <guiseq><gui>Proyecto</gui><gui>Carpeta nueva...</gui></guiseq> y creando una carpeta <file>berlin_images</file> como subcarpeta de la carpeta <file>mural-fotos</file>. Asegúrese de poner al menos doce imágenes en la carpeta.</p>
  <p>Cuando lo haya hecho, pulse <guiseq><gui>Construir</gui><gui>Construir proyecto</gui></guiseq> para construir todo otra vez, y entonces pulse <guiseq><gui>Ejecutar</gui><gui>Ejecutar</gui></guiseq> para iniciar la aplicación.</p>
  <p>Si todavía no lo ha hecho, elija la aplicación <file>Debug/src/photo-wall</file> en el diálogo que aparece. Finalmente, pulse <gui>Ejecutar</gui> y disfrute.</p>
</section>

<section id="impl">
 <title>Implementación de referencia</title>
 <p>Si tiene problemas con este tutorial, compare su código con este <link href="photo-wall/photo-wall.c">código de referencia</link>.</p>
</section>

</page>