From 77dfef58240c23a92c1a232d32055538d628ae6e Mon Sep 17 00:00:00 2001 From: Pierre-Luc Beaudoin Date: Sat, 2 May 2009 22:32:48 -0400 Subject: [PATCH] Complete MapSource documentation --- champlain/champlain-base-marker.c | 2 +- champlain/champlain-map-source-factory.c | 54 +++++++++++ champlain/champlain-map-source-factory.h | 8 ++ champlain/champlain-network-map-source.c | 110 ++++++++++++++++++----- champlain/champlain-network-map-source.h | 4 +- 5 files changed, 154 insertions(+), 24 deletions(-) diff --git a/champlain/champlain-base-marker.c b/champlain/champlain-base-marker.c index c7f9ae8..a402c7b 100644 --- a/champlain/champlain-base-marker.c +++ b/champlain/champlain-base-marker.c @@ -18,7 +18,7 @@ /** * SECTION:champlain-base-marker - * @short_description: a base marker to identify points of interest on a map + * @short_description: A base marker to identify points of interest on a map * * Base markers reprensent points of interest on a map. base markers need to be * placed on a layer (a #cluttergroup). layers have to be added to a diff --git a/champlain/champlain-map-source-factory.c b/champlain/champlain-map-source-factory.c index 2e51a39..67c379f 100644 --- a/champlain/champlain-map-source-factory.c +++ b/champlain/champlain-map-source-factory.c @@ -16,6 +16,21 @@ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ +/** + * SECTION:champlain-map-source-factory + * @short_description: Manages #ChamplainMapSource + * + * This factory manages the create of #ChamplainMapSource. It contains names + * and constructor functions for each available map sources in libchamplain. + * You can add your own with #champlain_map_source_factory_register. + * + * To get the wanted map source, use #champlain_map_source_factory_create. It + * will return a ready to use #ChamplainMapSource. + * + * To get the list of registered map sources, use + * #champlain_map_source_factory_get_list. + * + */ #include "config.h" #include "champlain-map-source-factory.h" @@ -143,6 +158,13 @@ champlain_map_source_factory_init (ChamplainMapSourceFactory *factory) champlain_map_source_new_mff_relief); } +/** + * champlain_map_source_factory_get_default: + * + * Returns the singleton #ChamplainMapSourceFactory + * + * Since: 0.4 + */ ChamplainMapSourceFactory * champlain_map_source_factory_get_default (void) { @@ -157,6 +179,14 @@ champlain_map_source_factory_get_default (void) return g_object_ref (instance); } +/** + * champlain_map_source_factory_get_list: + * + * Returns the list of registered map sources, the list should be freed with + * #g_strfreev. + * + * Since: 0.4 + */ gchar ** champlain_map_source_factory_get_list (ChamplainMapSourceFactory *factory) { @@ -182,6 +212,16 @@ champlain_map_source_factory_get_list (ChamplainMapSourceFactory *factory) return ret; } +/** + * champlain_map_source_factory_create: + * @factory: the Factory + * @name: the wanted map source name + * + * Returns a ready to use #ChamplainMapSource matching the given name, returns + * NULL is none match. + * + * Since: 0.4 + */ ChamplainMapSource * champlain_map_source_factory_create (ChamplainMapSourceFactory *factory, const gchar *name) @@ -200,6 +240,20 @@ champlain_map_source_factory_create (ChamplainMapSourceFactory *factory, return NULL; } +/** + * champlain_map_source_factory_register: + * @factory: the Factory + * @name: the new map source name + * @constructor: the new map source constructor function + * + * Register the new map source with the given constructor. When this map + * source is requested, the given constructor will be given to build the + * map source. + * + * Returns TRUE if the registration suceeded. + * + * Since: 0.4 + */ gboolean champlain_map_source_factory_register (ChamplainMapSourceFactory *factory, const gchar *name, diff --git a/champlain/champlain-map-source-factory.h b/champlain/champlain-map-source-factory.h index 5712223..c895987 100644 --- a/champlain/champlain-map-source-factory.h +++ b/champlain/champlain-map-source-factory.h @@ -61,6 +61,14 @@ gchar ** champlain_map_source_factory_get_list (ChamplainMapSourceFactory *facto ChamplainMapSource * champlain_map_source_factory_create (ChamplainMapSourceFactory *factory, const gchar *id); +/** + * ChamplainMapSourceConstructor: + * + * A #ChamplainMapSource constructor. It should return a ready to use + * #ChamplainMapSource. + * + * Since: 0.4 + */ typedef ChamplainMapSource * (*ChamplainMapSourceConstructor) (); #define CHAMPLAIN_MAP_SOURCE_CONSTRUCTOR (f) ((ChamplainMapSourceConstructor) (f)) diff --git a/champlain/champlain-network-map-source.c b/champlain/champlain-network-map-source.c index 0abb198..017d088 100644 --- a/champlain/champlain-network-map-source.c +++ b/champlain/champlain-network-map-source.c @@ -16,6 +16,20 @@ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ +/** + * SECTION:champlain-network-map-source + * @short_description: A base object for network map sources + * + * This object is specialized for map tiles that can be downloaded + * from a web server. This include all web based map services such as + * OpenStreetMap, Google Maps, Yahoo Maps and more. This object contains + * all mechanisms necessary to download and cache (with the help of + * #ChamplainCache) tiles. + * + * Some preconfigured network map sources are built-in this library, + * see #ChamplainMapSourceFactory. + * + */ #include "config.h" #include "champlain-network-map-source.h" @@ -84,8 +98,8 @@ champlain_network_map_source_get_property (GObject *object, GValue *value, GParamSpec *pspec) { - ChamplainNetworkMapSource *network_map_source = CHAMPLAIN_NETWORK_MAP_SOURCE(object); - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSource *source = CHAMPLAIN_NETWORK_MAP_SOURCE(object); + ChamplainNetworkMapSourcePrivate *priv = source->priv; switch(prop_id) { @@ -109,8 +123,8 @@ champlain_network_map_source_set_property (GObject *object, const GValue *value, GParamSpec *pspec) { - ChamplainNetworkMapSource *network_map_source = CHAMPLAIN_NETWORK_MAP_SOURCE(object); - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSource *source = CHAMPLAIN_NETWORK_MAP_SOURCE(object); + ChamplainNetworkMapSourcePrivate *priv = source->priv; switch(prop_id) { @@ -137,8 +151,8 @@ champlain_network_map_source_set_property (GObject *object, static void champlain_network_map_source_finalize (GObject *object) { - ChamplainNetworkMapSource *network_map_source = CHAMPLAIN_NETWORK_MAP_SOURCE (object); - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSource *source = CHAMPLAIN_NETWORK_MAP_SOURCE (object); + ChamplainNetworkMapSourcePrivate *priv = source->priv; g_free (priv->proxy_uri); g_free (priv->uri_format); @@ -164,7 +178,7 @@ champlain_network_map_source_class_init (ChamplainNetworkMapSourceClass *klass) /** * ChamplainNetworkMapSource:uri-format * - * The uri format for the map source + * The uri format for the map source, see #champlain_network_map_source_set_uri_format * * Since: 0.4 */ @@ -216,6 +230,21 @@ champlain_network_map_source_init (ChamplainNetworkMapSource *champlainMapSource priv->offline = FALSE; } +/** + * champlain_network_map_source_new_full: + * @name: the map source's name + * @license: the map source's license + * @license_uri: the map source's license URI + * @min_zoom: the map source's minimum zoom level + * @max_zoom: the map source's maximum zoom level + * @tile_size: the map source's tile size (in pixels) + * @projection: the map source's projection + * @uri_format: the URI to fetch the tiles from, see #champlain_network_map_source_set_uri_format + * + * Returns a constructed #ChamplainNetworkMapSource + * + * Since: 0.4 + */ ChamplainNetworkMapSource* champlain_network_map_source_new_full (const gchar *name, const gchar *license, @@ -226,23 +255,35 @@ champlain_network_map_source_new_full (const gchar *name, ChamplainMapProjection projection, const gchar *uri_format) { - ChamplainNetworkMapSource * network_map_source; - network_map_source = g_object_new (CHAMPLAIN_TYPE_NETWORK_MAP_SOURCE, "name", name, + ChamplainNetworkMapSource * source; + source = g_object_new (CHAMPLAIN_TYPE_NETWORK_MAP_SOURCE, "name", name, "license", license, "license-uri", license_uri, "min-zoom-level", min_zoom, "max-zoom-level", max_zoom, "tile-size", tile_size, "projection", projection, "uri-format", uri_format, NULL); - return network_map_source; + return source; } +/** + * champlain_network_map_source_get_tile_uri: + * @source: the #ChamplainNetworkMapSource + * @x: the x position of the tile + * @y: the y position of the tile + * @z: the zool level of the tile + * + * Returns a contruscted URI with the given parameters based on the map + * source's URI format. + * + * Since: 0.4 + */ #define SIZE 8 gchar * -champlain_network_map_source_get_tile_uri (ChamplainNetworkMapSource *network_map_source, +champlain_network_map_source_get_tile_uri (ChamplainNetworkMapSource *source, gint x, gint y, gint z) { - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSourcePrivate *priv = source->priv; gchar **tokens; gchar *token; @@ -282,25 +323,41 @@ champlain_network_map_source_get_tile_uri (ChamplainNetworkMapSource *network_ma return token; } +/** + * champlain_network_map_source_set_uri_format: + * @source: the #ChamplainNetworkMapSource + * @uri_format: the URI format + * + * A URI format is a URI where x, y and zoom level information have been + * marked for parsing and insertion. There can be an unlimited number of + * marked items in a URI format. They are delimited by "#" before and after + * the variable name. There are 3 defined variable names: X, Y, and Z. + * + * For example, this is the OpenStreetMap URI format: + * "http://tile.openstreetmap.org/#Z#/#X#/#Y#.png" + * + * + * Since: 0.4 + */ void -champlain_network_map_source_set_tile_uri (ChamplainNetworkMapSource *network_map_source, +champlain_network_map_source_set_uri_format (ChamplainNetworkMapSource *source, const gchar *uri_format) { - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSourcePrivate *priv = source->priv; g_free (priv->uri_format); priv->uri_format = g_strdup (uri_format); } static gchar * -get_filename (ChamplainNetworkMapSource *network_map_source, +get_filename (ChamplainNetworkMapSource *source, ChamplainTile *tile) { - //ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + //ChamplainNetworkMapSourcePrivate *priv = source->priv; return g_strdup_printf ("%s" G_DIR_SEPARATOR_S "%s" G_DIR_SEPARATOR_S "%s" G_DIR_SEPARATOR_S "%d" G_DIR_SEPARATOR_S "%d" G_DIR_SEPARATOR_S "%d.png", g_get_user_cache_dir (), - CACHE_SUBDIR, champlain_map_source_get_name (CHAMPLAIN_MAP_SOURCE (network_map_source)), + CACHE_SUBDIR, champlain_map_source_get_name (CHAMPLAIN_MAP_SOURCE (source)), champlain_tile_get_zoom_level (tile), champlain_tile_get_x (tile), champlain_tile_get_y (tile)); } @@ -490,6 +547,17 @@ finish: g_object_unref (tile); } +/** + * champlain_network_map_source_fill_tile: + * @map_source: the #ChamplainNetworkMapSource + * @tile: the #ChamplainTile + * + * Fills the passed tile with image data. If not in #ChamplainCache, this function + * will initiate an async download of the image at the map source's URI format. + * Once done, the tile's state will be set to #CHAMPLAIN_STATE_DONE. + * + * Since: 0.4 + */ void champlain_network_map_source_fill_tile (ChamplainMapSource *map_source, ChamplainTile *tile) @@ -499,12 +567,12 @@ champlain_network_map_source_fill_tile (ChamplainMapSource *map_source, gboolean validate_cache = FALSE; gint zoom_level = champlain_tile_get_zoom_level (tile); - ChamplainNetworkMapSource *network_map_source = CHAMPLAIN_NETWORK_MAP_SOURCE (map_source); - ChamplainNetworkMapSourcePrivate *priv = network_map_source->priv; + ChamplainNetworkMapSource *source = CHAMPLAIN_NETWORK_MAP_SOURCE (map_source); + ChamplainNetworkMapSourcePrivate *priv = source->priv; ChamplainCache *cache = champlain_cache_get_default (); /* Try the cached version first */ - filename = get_filename (network_map_source, tile); + filename = get_filename (source, tile); champlain_tile_set_filename (tile, filename); champlain_tile_set_size (tile, champlain_map_source_get_tile_size (map_source)); @@ -542,7 +610,7 @@ champlain_network_map_source_fill_tile (ChamplainMapSource *map_source, #endif NULL); - uri = champlain_network_map_source_get_tile_uri (network_map_source, + uri = champlain_network_map_source_get_tile_uri (source, champlain_tile_get_x (tile), champlain_tile_get_y (tile), zoom_level); champlain_tile_set_uri (tile, uri); diff --git a/champlain/champlain-network-map-source.h b/champlain/champlain-network-map-source.h index 138fcb1..f7a4fdf 100644 --- a/champlain/champlain-network-map-source.h +++ b/champlain/champlain-network-map-source.h @@ -56,7 +56,7 @@ GType champlain_network_map_source_get_type (void); ChamplainNetworkMapSource* champlain_network_map_source_new_full ( const gchar *name, const gchar *license, const gchar *license_uri, - guint min_zoom, guint map_zoom, guint tile_size, + guint min_zoom, guint max_zoom, guint tile_size, ChamplainMapProjection projection, const gchar *uri_format); gchar * champlain_network_map_source_get_tile_uri (ChamplainNetworkMapSource *source, @@ -64,7 +64,7 @@ gchar * champlain_network_map_source_get_tile_uri (ChamplainNetworkMapSource *so gint y, gint z); -void champlain_network_map_source_set_tile_uri (ChamplainNetworkMapSource *network_map_source, +void champlain_network_map_source_set_uri_format (ChamplainNetworkMapSource *source, const gchar *uri_format); void champlain_network_map_source_fill_tile (ChamplainMapSource *map_source, -- 2.39.5