# Mural de fotos (C)

Un visor de imágenes Clutter
Chris Kühl
chrisk@openismus.com
Johannes Schmid
jhs@gnome.org
Marta Maria Casetti
mmcasetti@gmail.com 2013
Daniel Mustieles
daniel.mustieles@gmail.com 2011 - 2020
Nicolás Satragno
nsatragno@gmail.com 2012 - 2013
Jorge González
jorgegonz@svn.gnome.org 2011

# Mural de fotos

      Para este ejemplo se construirá un sencillo visor de imágenes usando Clutter. Aprenderá:

        Cómo dimensionar y posicionar varios ClutterActor
        Cómo situar una imagen en un ClutterActor
        Cómo hacer transiciones sencillas usando el entorno de trabajo de animaciones de Clutter
        Cómo hacer que un ClutterActor responda a los eventos del ratón
        Cómo obtener nombres de archivos de una carpeta

# Introducción

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.

Para ayudarle a conseguir su objetivo, también se utilizarán algunos fragmentos comunes de GLib. Más importante es que se usará un `GPtrArray`, una matriz dinámica de punteros, para mantener los nombres de ruta de archivos. También se usará `GDir`, una utilidad para trabajar dentro de carpetas, para acceder a la carpeta de imágenes y obtener las rutas de archivo.

# Crear un proyecto en Anjuta

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.

Inicie Anjuta y pulse ArchivoNuevoProyecto para abrir el asistente de proyectos.

Seleccione GTK+ (simple) en la pestaña C, pulse Continuar, y rellene los detalles en las siguientes páginas. Use mural-de-fotos como nombre del proyecto y de la carpeta.

Asegúrese de que Usar GtkBuilder para la interfaz del usuario está desactivado, ya que, en este tutorial, la IU se creará manualmente. Revise el tutorial del afinador de guitarra usando el constructor de interfaces.

Active Configurar paquetes externos. En la página siguiente, seleccione clutter-1.0 de la lista para incluir la biblioteca Clutter en su proyecto.

Pulse Aplicar y se creará el proyecto. Abra src/main.c desde las pestañas Proyecto o Archivo. Debería ver algo de código que comience con las líneas:

#include <config.h> #include <gtk/gtk.h>

# Un vistazo al mural de fotos

El visor de imágenes muestra al usuario un mural de imágenes.

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.

# Configuración inicial

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 src/main.c:

#include <gdk-pixbuf/gdk-pixbuf.h> #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 IMAGE_DIR_PATH "./berlin_images/"

static GPtrArray *img_paths;

static ClutterPoint unfocused_pos;

# Saltar dentro del código

Se empezará echando un vistazo a la función `main()` completa. Luego se verá el resto de secciones del código en detalle. Cambie el archivo src/main.c para que contenga la función `main()`. Puede eliminar la función `create_window()`, ya que no se usa en este ejemplo.

int main(int argc, char *argv[]) { ClutterColor stage_color = { 16, 16, 16, 255 }; ClutterActor *stage = NULL;

if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS) return 1;

stage = clutter_stage_new(); clutter_actor_set_size(stage, STAGE_WIDTH, STAGE_HEIGHT); clutter_actor_set_background_color(stage, &stage_color); clutter_stage_set_title(CLUTTER_STAGE (stage), "Photo Wall"); g_signal_connect(stage, "destroy", G_CALLBACK(clutter_main_quit), NULL);

load_image_path_names();

guint row = 0; guint col = 0; for(row=0; row < ROW_COUNT; ++row) { for(col=0; col < COL_COUNT; ++col) { const char *img_path = g_ptr_array_index(img_paths, (row * COL_COUNT) + col); GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file_at_size(img_path, STAGE_HEIGHT, STAGE_HEIGHT, NULL); ClutterContent *image = clutter_image_new (); ClutterActor *actor = clutter_actor_new ();

if (pixbuf != NULL) { clutter_image_set_data(CLUTTER_IMAGE(image), gdk_pixbuf_get_pixels(pixbuf), gdk_pixbuf_get_has_alpha(pixbuf) ? COGL_PIXEL_FORMAT_RGBA_8888 : COGL_PIXEL_FORMAT_RGB_888, gdk_pixbuf_get_width(pixbuf), gdk_pixbuf_get_height(pixbuf), gdk_pixbuf_get_rowstride(pixbuf), NULL); }

clutter_actor_set_content(actor, image); g_object_unref(image); g_object_unref(pixbuf);

initialize_actor(actor, row, col); clutter_actor_add_child(stage, actor); } }

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

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

g_ptr_array_unref(img_paths);

return 0; }

Línea 4: `ClutterColor` 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.

Línea 7: debe inicializar Clutter. Si olvida hacerlo, obtendrá mensajes muy extraños. Queda advertido.

Líneas 10-14: aquí es donde se crea un `ClutterStage` nuevo. Entonces se establece el tamaño usando el definido en la sección anterior y la dirección del `ClutterColor` que ya está definida.

Un `ClutterStage` es el nivel superior de un `ClutterActor` en el que se ubican otros `ClutterActor`.

Línea 16: aquí se llama a la función para obtener las rutas de las imágenes. Esto se verá en breve.

Líneas 18-49: aquí es donde se configuran los `ClutterActor`, 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.

Línea 52: mostrar el escenario y todos sus hijos, es decir, las imágenes.

Línea 55: iniciar el bucle principal de Clutter.

# Configurar los actores de imagen

En Clutter, un actor es el elemento visual más simple. Básicamente, todo lo que ve es un actor.

En esta sección, se va a mirar más detenidamente el bucle usado para configurar los `ClutterActor` que mostrarán las imágenes.

guint row = 0; guint col = 0; for(row=0; row < ROW_COUNT; ++row) { for(col=0; col < COL_COUNT; ++col) { const char *img_path = g_ptr_array_index(img_paths, (row * COL_COUNT) + col); GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file_at_size(img_path, STAGE_HEIGHT, STAGE_HEIGHT, NULL); ClutterContent *image = clutter_image_new (); ClutterActor *actor = clutter_actor_new ();

if (pixbuf != NULL) { clutter_image_set_data(CLUTTER_IMAGE(image), gdk_pixbuf_get_pixels(pixbuf), gdk_pixbuf_get_has_alpha(pixbuf) ? COGL_PIXEL_FORMAT_RGBA_8888 : COGL_PIXEL_FORMAT_RGB_888, gdk_pixbuf_get_width(pixbuf), gdk_pixbuf_get_height(pixbuf), gdk_pixbuf_get_rowstride(pixbuf), NULL); }

clutter_actor_set_content(actor, image); g_object_unref(image); g_object_unref(pixbuf);

initialize_actor(actor, row, col); clutter_actor_add_child(stage, actor); } }

Línea 7: aquí se quiere obtener la ruta a la ubicación número n en el `GPtrArray` que contiene los nombres de las rutas de las imágenes. La posición número n se calcula basándose en `row` y `col`.

Líneas 8-23: aquí es donde se crea el `ClutterActor` en sí y se ubica la imagen en el actor. El primer argumento es la ruta a la que se accede con el nodo de la `GSList`. El segundo argumento es para informar de un error, pero se ignora para simplificar.

Línea 47: esta añade el `ClutterActor` al escenario, que es un contenedor. Asume propiedad del `ClutterActor`, que es algo que querrá cuando profundice en el desarrollo de GNOME. Para obtener más detalles, consulte la documentación de `GObject`.

# Cargar las imágenes

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.

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

img_paths = g_ptr_array_new_with_free_func (g_free);

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); g_ptr_array_add (img_paths, path); } filename = g_dir_read_name(dir); } }

Líneas 5 y 12: esto abre la carpeta o, si ocurre un error, termina después de mostrar un mensaje de error.

Líneas 16-25: la primera línea obtiene otro nombre de archivo del `GDir` 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 el nombre de la siguiente ruta y se vuelve a entrar en el bucle si se encuentra otro archivo.

# Configurar los actores

Eche un vistazo al tamaño y al posicionamiento de los `ClutterActor` y a cómo se deja listo el `ClutterActor` para la interacción del usuario.

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

Línea 7: configurar un actor como «reactivo» significa que reacciona a los eventos tales como `button-press-event` en nuestro caso. Para el mural de fotos, todos los `ClutterActor` del mural deben ser inicialmente reactivos.

Líneas 9‒12: ahora se conecta el evento `button-press-event` al retorno de la llamada `actor_clicked_cb` que veremos más adelante.

En este punto tiene un mural de fotos que está listo para verse.

# Reaccionar a las pulsaciones

static gboolean actor_clicked_cb(ClutterActor *actor, ClutterEvent *event, gpointer user_data) { /* Flag to keep track of our state. */ static gboolean is_focused = FALSE; ClutterActorIter iter; ClutterActor *child;

/* Reset the focus state on all the images */ clutter_actor_iter_init (&iter, clutter_actor_get_parent(actor)); while (clutter_actor_iter_next(&iter, &child)) clutter_actor_set_reactive(child, is_focused);

clutter_actor_save_easing_state(actor); clutter_actor_set_easing_duration(actor, ANIMATION_DURATION_MS);

if(is_focused) { /* Restore the old location and size. */ clutter_actor_set_position(actor, unfocused_pos.x, unfocused_pos.y); clutter_actor_set_size(actor, THUMBNAIL_SIZE, THUMBNAIL_SIZE); } else { /* Save the current location before animating. */ clutter_actor_get_position(actor, &unfocused_pos.x, &unfocused_pos.y); /* Only the currently focused image should receive events. */ clutter_actor_set_reactive(actor, TRUE);

/* Put the focused image on top. */ clutter_actor_set_child_above_sibling(clutter_actor_get_parent(actor), actor, NULL);

clutter_actor_set_position(actor, (STAGE_WIDTH - STAGE_HEIGHT) / 2.0, 0); clutter_actor_set_size(actor, STAGE_HEIGHT, STAGE_HEIGHT); }

clutter_actor_restore_easing_state(actor);

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

return TRUE; }

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 `button_clicked_event`. En este ejemplo, sólo se usará el primer argumento, el `ClutterActor` pulsado actualmente.

Unas pocas palabras sobre los argumentos que no se están usando en este ejemplo. El `ClutterEvent` es diferente dependiendo de qué evento se está manejando. Por ejemplo, un evento de clave produce un `ClutterKeyEvent` desde el que puede obtener la clave pulsada, entre otra información. Para eventos de pulsaciones del ratón, obtiene un `ClutterButtonEvent` con el que pueden obtener los valores `x` e `y`. Consulte la documentación de Clutter para obtener información sobre otros tipos de `ClutterEvent`.

El `user_data` es lo que se usa para pasar datos a la función. Se puede pasar un puntero a cualquier tipo de datos. Si necesita pasar varios datos al retorno de la llamada, puede colocarlos en una estructura y pasar un puntero a su dirección.

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 `FALSE`.

Líneas 12-14: configuran los actores de imágenes para recibir eventos si obtienen el foco.

Línea 16-17: aquí se establece la duración de la animación y se guarda el estado actual.

Líneas 21-23: llegar a este código significa que actualmente solo una imagen tiene el foco, y se quiere volver al modo mural. Establecer una posición en un `ClutterActor` comienza una animación con la duración configurada en la línea 17.

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 `ClutterActor`. Aquí se guarda la posición inicial, por lo que se puede volver a ella más adelante.

Línea 25: establecer la propiedad `reactive` del `ClutterActor` a `TRUE` hace que este `ClutterActor` reaccione a los eventos. En el estado «con foco», el único `ClutterActor` que se quiere que reciba eventos es el `ClutterActor` que se está viendo. Al pulsar sobre el `ClutterActor` volverá a su posición inicial.

Líneas 27-36: aquí es donde se guarda la posición actual de la imagen, se configura para recibir eventos y se hace que aparezca sobre las otras, comenzando la animación para que llene el escenario.

Línea 39: aquí se restaura el estado a lo que era antes de que se cambiara en la línea 16.

Línea 42: aquí se alterna la opción `is_focused` al estado actual.

Como se ha mencionado anteriormente, los `ClutterActor` con valores de `depth` más altos recibirán eventos, pero pueden permitir que los `ClutterActor` que están por denajo de ellos también reciban eventos. Al devolver `TRUE` se dejarán de enviar eventos havia abajo, mientras que `FALSE` hará que los eventos pasen hacia abajo.

Recuerde, sin embargo, que para que los `ClutterActor` reciban eventos deben establecerse como `reactive`.

# Construir y ejecutar la aplicación

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 berlin_images. Si quiere, puede cambiar la línea `#define IMAGE_DIR_PATH` del principio para que haga referencia a su carpeta de fotos, o crear una carpeta berlin_images pulsando en ProyectoCarpeta nueva... y creando una carpeta berlin_images como subcarpeta de la carpeta mural-fotos. Asegúrese de poner al menos doce imágenes en la carpeta.

Cuando lo haya hecho, pulse ConstruirConstruir proyecto para construir todo otra vez, y entonces pulse EjecutarEjecutar para iniciar la aplicación.

Si todavía no lo ha hecho, elija la aplicación Debug/src/photo-wall en el diálogo que aparece. Finalmente, pulse Ejecutar y disfrute.

# Implementación de referencia

Si tiene problemas con este tutorial, compare su código con este código de referencia.