Add as_screenshot_get_image_for_locale()

The AppStream specification has recently added the ability to have translated
screenshot images. To support this add new methods to restrict the AsImage
selection to compatible locales.

1 files changed, 70 insertions, 8 deletions

diff --git a/libappstream-glib/as-screenshot.c b/libappstream-glib/as-screenshot.c
index a574e94..9be5061 100644
--- a/libappstream-glib/as-screenshot.c
+++ b/libappstream-glib/as-screenshot.c
@@ -1,6 +1,6 @@
 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
  *
- * Copyright (C) 2014 Richard Hughes <richard@hughsie.com>
+ * Copyright (C) 2014-2016 Richard Hughes <richard@hughsie.com>
  *
  * Licensed under the GNU Lesser General Public License Version 2.1
  *
@@ -168,7 +168,7 @@ as_screenshot_get_priority (AsScreenshot *screenshot)
  * as_screenshot_get_images:
  * @screenshot: a #AsScreenshot instance.
  *
- * Gets the image sizes included in the screenshot.
+ * Gets the images included in the screenshot of all sizes and locales.
  *
  * Returns: (element-type AsImage) (transfer none): an array
  *
@@ -182,21 +182,58 @@ as_screenshot_get_images (AsScreenshot *screenshot)
 }
 
 /**
- * as_screenshot_get_image:
+ * as_screenshot_get_images_for_locale:
  * @screenshot: a #AsScreenshot instance.
+ *
+ * Returns all images of all sizes that are compatible with a specific locale.
+ *
+ * Returns: (element-type AsImage) (transfer container): an array
+ *
+ * Since: 0.5.14
+ **/
+GPtrArray *
+as_screenshot_get_images_for_locale (AsScreenshot *screenshot,
+				    const gchar *locale)
+{
+	AsImage *im;
+	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
+	GPtrArray *array;
+	guint i;
+
+	/* user wants a specific locale */
+	array = g_ptr_array_new_with_free_func ((GDestroyNotify) g_object_unref);
+	for (i = 0; i < priv->images->len; i++) {
+		im = g_ptr_array_index (priv->images, i);
+		if (!as_utils_locale_is_compatible (as_image_get_locale (im),
+						    locale))
+			continue;
+		g_ptr_array_add (array, g_object_ref (im));
+	}
+	return array;
+}
+
+/**
+ * as_screenshot_get_image_for_locale:
+ * @screenshot: a #AsScreenshot instance.
+ * @locale: locale, or %NULL
  * @width: target width
  * @height: target height
  *
- * Gets the AsImage closest to the target size. The #AsImage may not actually
- * be the requested size, and the application may have to pad / rescale the
- * image to make it fit.
+ * Gets the AsImage closest to the target size with the specified locale.
+ * The #AsImage may not actually be the requested size, and the application may
+ * have to pad / rescale the image to make it fit.
+ *
+ * FIXME: This function assumes the images are ordered in preference order, e.g.
+ * "en_GB -> en -> NULL"
  *
  * Returns: (transfer none): an #AsImage, or %NULL
  *
- * Since: 0.2.2
+ * Since: 0.5.14
  **/
 AsImage *
-as_screenshot_get_image (AsScreenshot *screenshot, guint width, guint height)
+as_screenshot_get_image_for_locale (AsScreenshot *screenshot,
+				    const gchar *locale,
+				    guint width, guint height)
 {
 	AsImage *im;
 	AsImage *im_best = NULL;
@@ -209,6 +246,8 @@ as_screenshot_get_image (AsScreenshot *screenshot, guint width, guint height)
 
 	for (i = 0; i < priv->images->len; i++) {
 		im = g_ptr_array_index (priv->images, i);
+		if (!as_utils_locale_is_compatible (as_image_get_locale (im), locale))
+			continue;
 		tmp = ABS ((gint64) (width * height) -
 			   (gint64) (as_image_get_width (im) * as_image_get_height (im)));
 		if (tmp < best_size) {
@@ -220,6 +259,29 @@ as_screenshot_get_image (AsScreenshot *screenshot, guint width, guint height)
 }
 
 /**
+ * as_screenshot_get_image:
+ * @screenshot: a #AsScreenshot instance.
+ * @width: target width
+ * @height: target height
+ *
+ * Gets the AsImage closest to the target size. The #AsImage may not actually
+ * be the requested size, and the application may have to pad / rescale the
+ * image to make it fit.
+ *
+ * Returns: (transfer none): an #AsImage, or %NULL
+ *
+ * Since: 0.2.2
+ **/
+AsImage *
+as_screenshot_get_image (AsScreenshot *screenshot, guint width, guint height)
+{
+	return as_screenshot_get_image_for_locale (screenshot,
+						   NULL, /* locale */
+						   width,
+						   height);
+}
+
+/**
  * as_screenshot_get_source:
  * @screenshot: a #AsScreenshot instance.
  *