[libchamplain] Documentation and formatting changes for the overlay sources

[Jiří Techet <jiritechet src gnome org>]

commit 1bf7575f26bcc7773580c825440f0921598d4e06
Author: Jiří Techet <techet gmail com>
Date:   Wed Aug 21 14:48:22 2013 +0200

    Documentation and formatting changes for the overlay sources

 champlain/champlain-map-source-factory.c |    4 +-
 champlain/champlain-view.c               |   72 ++++++++++++++++++++---------
 champlain/champlain-view.h               |    2 +-
 docs/reference/libchamplain-sections.txt |    8 +++
 4 files changed, 61 insertions(+), 25 deletions(-)
---
diff --git a/champlain/champlain-map-source-factory.c b/champlain/champlain-map-source-factory.c
index 8832d81..0fc65ac 100644
--- a/champlain/champlain-map-source-factory.c
+++ b/champlain/champlain-map-source-factory.c
@@ -482,6 +482,7 @@ champlain_map_source_factory_create_cached_source (ChamplainMapSourceFactory *fa
   return CHAMPLAIN_MAP_SOURCE (source_chain);
 }
 
+
 /**
  * champlain_map_source_factory_create_memcached_source:
  * @factory: the Factory
@@ -492,7 +493,7 @@ champlain_map_source_factory_create_cached_source (ChamplainMapSourceFactory *fa
  * Returns: (transfer none): a ready to use #ChamplainMapSourceChain consisting of
  * #ChamplainMemoryCache and #ChamplainMapSource matching the given name
  *
- * Since: 0.6
+ * Since: 0.12.5
  */
 ChamplainMapSource *
 champlain_map_source_factory_create_memcached_source (ChamplainMapSourceFactory *factory,
@@ -515,6 +516,7 @@ champlain_map_source_factory_create_memcached_source (ChamplainMapSourceFactory
   return CHAMPLAIN_MAP_SOURCE (source_chain);
 }
 
+
 /**
  * champlain_map_source_factory_create_error_source:
  * @factory: the Factory
diff --git a/champlain/champlain-view.c b/champlain/champlain-view.c
index eed2c47..d69fff0 100644
--- a/champlain/champlain-view.c
+++ b/champlain/champlain-view.c
@@ -162,7 +162,7 @@ struct _ChamplainViewPrivate
   gint viewport_height;
 
   ChamplainMapSource *map_source; /* Current map tile source */
-  GList *all_sources;
+  GList *overlay_sources;
 
   guint zoom_level; /* Holds the current zoom level number */
   guint min_zoom_level; /* Lowest allowed zoom level */
@@ -607,8 +607,8 @@ champlain_view_dispose (GObject *object)
       priv->map_source = NULL;
     }
 
-  g_list_free_full (priv->all_sources, g_object_unref);
-  priv->all_sources = NULL;
+  g_list_free_full (priv->overlay_sources, g_object_unref);
+  priv->overlay_sources = NULL;
 
   if (priv->background_content)
     {
@@ -1902,13 +1902,14 @@ tile_in_tile_map (ChamplainView *view, gint tile_x, gint tile_y)
   return GPOINTER_TO_INT (g_hash_table_lookup (priv->tile_map, &key));
 }
 
+
 static void
-load_tile_for_source (ChamplainView      *view,
-                      ChamplainMapSource *source,
-                      int                 opacity,
-                      int                 size,
-                      int                 x,
-                      int                 y)
+load_tile_for_source (ChamplainView *view,
+    ChamplainMapSource *source,
+    gint opacity,
+    gint size,
+    gint x,
+    gint y)
 {
   ChamplainViewPrivate *priv = view->priv;
   ChamplainTile *tile = champlain_tile_new ();
@@ -1935,6 +1936,7 @@ load_tile_for_source (ChamplainView      *view,
     g_object_set_data (G_OBJECT (tile), "overlay", GINT_TO_POINTER (TRUE));
 }
 
+
 static gboolean
 fill_tile_cb (FillTileCallbackData *data)
 {
@@ -1953,11 +1955,11 @@ fill_tile_cb (FillTileCallbackData *data)
       GList *iter;
 
       load_tile_for_source (view, priv->map_source, 255, size, x, y);
-      for (iter = priv->all_sources; iter; iter = iter->next)
-        load_tile_for_source (view, iter->data,
-                              GPOINTER_TO_INT (g_object_get_data (G_OBJECT (iter->data),
-                                                                  "opacity")),
-                              size, x, y);
+      for (iter = priv->overlay_sources; iter; iter = iter->next)
+        {
+          gint opacity = GPOINTER_TO_INT (g_object_get_data (G_OBJECT (iter->data), "opacity"));
+          load_tile_for_source (view, iter->data, opacity, size, x, y);
+        }
 
       tile_map_set (view, x, y, TRUE);
     }
@@ -1968,6 +1970,7 @@ fill_tile_cb (FillTileCallbackData *data)
   return FALSE;
 }
 
+
 static void
 load_visible_tiles (ChamplainView *view,
     gboolean relocate)
@@ -2183,8 +2186,8 @@ champlain_view_set_map_source (ChamplainView *view,
   g_object_unref (priv->map_source);
   priv->map_source = g_object_ref_sink (source);
 
-  g_list_free_full (priv->all_sources, g_object_unref);
-  priv->all_sources = NULL;
+  g_list_free_full (priv->overlay_sources, g_object_unref);
+  priv->overlay_sources = NULL;
 
   priv->min_zoom_level = champlain_map_source_get_min_zoom_level (priv->map_source);
   priv->max_zoom_level = champlain_map_source_get_max_zoom_level (priv->map_source);
@@ -3047,10 +3050,22 @@ champlain_view_get_bounding_box (ChamplainView *view)
   return bbox;
 }
 
+
+/**
+ * champlain_view_add_overlay_source:
+ * @view: a #ChamplainView
+ * @source: a #ChamplainMapSource
+ * @opacity: opacity to use
+ *
+ * Adds a new overlay map source to render tiles with the supplied opacity on top 
+ * of the ordinary map source. Multiple overlay sources can be added.
+ *
+ * Since: 0.12.5
+ */
 void
-champlain_view_add_overlay_source (ChamplainView      *view,
-                                   ChamplainMapSource *source,
-                                   guint8              opacity)
+champlain_view_add_overlay_source (ChamplainView *view,
+    ChamplainMapSource *source,
+    guint8 opacity)
 {
   DEBUG_LOG ()
 
@@ -3060,15 +3075,26 @@ champlain_view_add_overlay_source (ChamplainView      *view,
   g_return_if_fail (CHAMPLAIN_IS_MAP_SOURCE (source));
 
   priv = view->priv;
-  priv->all_sources = g_list_append (priv->all_sources, g_object_ref (source));
+  g_object_ref (source);
+  priv->overlay_sources = g_list_append (priv->overlay_sources, source);
   g_object_set_data (G_OBJECT (source), "opacity", GINT_TO_POINTER (opacity));
 
   champlain_view_reload_tiles (view);
 }
 
+
+/**
+ * champlain_view_remove_overlay_source:
+ * @view: a #ChamplainView
+ * @source: a #ChamplainMapSource
+ *
+ * Removes an overlay source from #ChamplainView.
+ *
+ * Since: 0.12.5
+ */
 void
-champlain_view_remove_overlay_source (ChamplainView      *view,
-                                      ChamplainMapSource *source)
+champlain_view_remove_overlay_source (ChamplainView *view,
+    ChamplainMapSource *source)
 {
   DEBUG_LOG ()
 
@@ -3078,7 +3104,7 @@ champlain_view_remove_overlay_source (ChamplainView      *view,
   g_return_if_fail (CHAMPLAIN_IS_MAP_SOURCE (source));
 
   priv = view->priv;
-  priv->all_sources = g_list_remove (priv->all_sources, source);
+  priv->overlay_sources = g_list_remove (priv->overlay_sources, source);
   g_object_unref (source);
 
   champlain_view_reload_tiles (view);
diff --git a/champlain/champlain-view.h b/champlain/champlain-view.h
index 18fea0a..f3b95b9 100644
--- a/champlain/champlain-view.h
+++ b/champlain/champlain-view.h
@@ -109,7 +109,7 @@ void champlain_view_set_map_source (ChamplainView *view,
     ChamplainMapSource *map_source);
 void champlain_view_add_overlay_source (ChamplainView *view,
     ChamplainMapSource *map_source,
-    guint8              opacity);
+    guint8 opacity);
 void champlain_view_remove_overlay_source (ChamplainView *view,
     ChamplainMapSource *map_source);
 
diff --git a/docs/reference/libchamplain-sections.txt b/docs/reference/libchamplain-sections.txt
index 529943a..6a91ab2 100644
--- a/docs/reference/libchamplain-sections.txt
+++ b/docs/reference/libchamplain-sections.txt
@@ -132,6 +132,8 @@ champlain_view_set_max_zoom_level
 champlain_view_ensure_visible
 champlain_view_ensure_layers_visible
 champlain_view_set_map_source
+champlain_view_add_overlay_source
+champlain_view_remove_overlay_source
 champlain_view_set_deceleration
 champlain_view_set_kinetic_mode
 champlain_view_set_keep_center_on_resize
@@ -436,6 +438,7 @@ ChamplainMapSourceFactory
 champlain_map_source_factory_dup_default
 champlain_map_source_factory_create
 champlain_map_source_factory_create_cached_source
+champlain_map_source_factory_create_memcached_source
 champlain_map_source_factory_create_error_source
 champlain_map_source_factory_register
 champlain_map_source_factory_get_registered
@@ -447,6 +450,11 @@ CHAMPLAIN_MAP_SOURCE_OSM_MAPQUEST
 CHAMPLAIN_MAP_SOURCE_MFF_RELIEF
 CHAMPLAIN_MAP_SOURCE_OAM
 CHAMPLAIN_MAP_SOURCE_OSM_OSMARENDER
+CHAMPLAIN_MAP_SOURCE_OWM_CLOUDS
+CHAMPLAIN_MAP_SOURCE_OWM_PRECIPITATION
+CHAMPLAIN_MAP_SOURCE_OWM_PRESSURE
+CHAMPLAIN_MAP_SOURCE_OWM_TEMPERATURE
+CHAMPLAIN_MAP_SOURCE_OWM_WIND
 CHAMPLAIN_MAP_SOURCE_MEMPHIS_LOCAL
 CHAMPLAIN_MAP_SOURCE_MEMPHIS_NETWORK
 <SUBSECTION Standard>