From d040a4a8c0e7b0ebf6ae1463b51ba7c0923e9440 Mon Sep 17 00:00:00 2001 From: Kaj-Michael Lang Date: Thu, 22 May 2008 11:33:03 +0300 Subject: [PATCH] MapWidget: Start to add proper gtk-doc documentation comments --- libs/libgtkmap/gtkmap.c | 119 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/libs/libgtkmap/gtkmap.c b/libs/libgtkmap/gtkmap.c index 7dc5c6d..d316ffa 100644 --- a/libs/libgtkmap/gtkmap.c +++ b/libs/libgtkmap/gtkmap.c @@ -17,6 +17,18 @@ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** + * SECTION:gtk_map + * @short_description: A tile based map display widget + * @stability: unstable + * + * #GtkMap is simple map widget for displaying bitmap tile (256x256) based maps. + * + * + */ + + #include "config.h" #include @@ -326,6 +338,15 @@ static guint gtk_map_signals[LAST_SIGNAL] = { 0 }; /******************************************************************************/ +/** + * latlon2unit: + * @lat: Latitude to convert + * @lon: Longitude to convert + * @unitx: Pointer to result unit x + * @unity: Pointer to result unit y + * + * Helper function to convert from given lat,lon to map unit coordinates. + */ void latlon2unit(gdouble lat, gdouble lon, guint *unitx, guint *unity) { @@ -336,6 +357,16 @@ tmp=sin(lat * (M_PIl / 180.f)); *unity=lrint((GTK_MAP_WORLD_SIZE_UNITS / MERCATOR_SPAN) * (log((1.f + tmp) / (1.f - tmp)) * 0.5f - MERCATOR_TOP)); } +/** + * unit2latlon: + * @unitx: unit x to convert + * @unity: unit y to convert + * @lat: Pointer to Latitude result + * @lon: Pointer to Longitude result + * + * Helper to convert from given map unit coordinates back to real lat,lon. + */ + void unit2latlon(guint unitx, guint unity, gdouble *lat, gdouble *lon) { @@ -1044,6 +1075,11 @@ if (path->type==PATH_TYPE_ROUTE) #endif } +/** + * gtk_map_set_path_display: + * + * Set displaying option for different path types. + */ void gtk_map_set_path_display(GtkWidget *widget, gint path_mask) { @@ -1081,6 +1117,12 @@ for (iter=priv->paths; iter!=NULL; iter=iter->next) { } } +/** + * gtk_map_add_path: + * @path: A path object to add to the map + * + * Adds a new path to the map. + */ gboolean gtk_map_add_path(GtkWidget *widget, Path *path) { @@ -1101,6 +1143,12 @@ priv->paths=g_slist_append(priv->paths, path); return TRUE; } +/** + * gtk_map_remove_path: + * @path: A paths to remove that has been previously added to the map + * + * Remove given path object from the map. + */ gboolean gtk_map_remove_path(GtkWidget *widget, Path *path) { @@ -1666,6 +1714,13 @@ if (se==0) { return pixbuf; } +/** + * gtk_map_set_tile_repository: + * + * Set the map bitmap tile repository object to use. The map does not in itself + * handle downloading of loading of bitmaps. The repository object does that. + * + */ void gtk_map_set_tile_repository(GtkWidget *widget, RepoData *rd) { @@ -1741,6 +1796,14 @@ return TRUE; /******************************************************************************/ +/** + * gtk_map_set_center_mode: + * @mode: Centering mode + * + * Set how and where the map will center itself. Default mode is CENTER_MANUAL. + * CENTER_LATLON will center exactly on the current track tail. + * A track must be active to use any other mode than CENTER_MANUAL. + */ gboolean gtk_map_set_center_mode(GtkWidget *widget, GtkMapCenterMode mode) { @@ -1775,6 +1838,13 @@ if (priv->current_track) { } +/** + * gtk_map_set_center: + * @unitx: Map unit x to center on + * @unity: Map unit y to center on + * + * Center the map view on given map unit coordinates. + */ void gtk_map_set_center(GtkWidget *widget, guint unitx, guint unity) { @@ -1867,6 +1937,13 @@ gtk_map_refresh(widget); g_signal_emit(widget, gtk_map_signals[MAP_LOCATION_CHANGED], 0, priv->zoom); } +/** + * gtk_map_set_center_latlon: + * @lat: Latitude to center on + * @lon: Longitude to center on + * + * Centers map view on given lat,lon + */ void gtk_map_set_center_latlon(GtkWidget *widget, gdouble lat, gdouble lon) { @@ -1877,6 +1954,13 @@ latlon2unit(lat, lon, &unitx, &unity); gtk_map_set_center(widget, unitx, unity); } +/** + * gtk_map_get_center_latlon: + * @lat: Pointer to result + * @lon: Pointer to result + * + * Get the current map view center point in lat,lon + */ void gtk_map_get_center_latlon(GtkWidget *widget, gdouble *lat, gdouble *lon) { @@ -1890,6 +1974,13 @@ priv=GTK_MAP_GET_PRIVATE(map); unit2latlon(priv->center.unitx, priv->center.unity, lat, lon); } +/** + * gtk_map_pan: + * @delta_x: + * @delta_y: + * + * Pan map view using the given deltas. + */ void gtk_map_pan(GtkWidget *widget, gint delta_x, gint delta_y) { @@ -1904,6 +1995,16 @@ priv->center_mode=CENTER_MANUAL; gtk_map_set_center(widget, priv->center.unitx + delta_x*GTK_MAP_PAN_UNITS, priv->center.unity + delta_y*GTK_MAP_PAN_UNITS); } +/** + * gtk_map_rotate: + * @angle: The angle, in degress, to rotate the map view. + * + * Only available if build with cairo support! + * + * Rotates the map view around the current center point. + * + * Returns TRUE if rotation was possible, otherwise FALSE. + */ gboolean gtk_map_rotate(GtkWidget *widget, gfloat angle) { @@ -1928,6 +2029,11 @@ return FALSE; #endif } +/** + * gtk_map_refresh: + * + * Force a redraw of the map view. + */ void gtk_map_refresh(GtkWidget *widget) { @@ -2053,6 +2159,14 @@ return FALSE; /******************************************************************************/ +/** + * gtk_map_set_context_menu: + * @menu: A #GtkMenu to add as context menu + * + * Add a context menu to display when the map is clicked on with the right mouse button. + * On hildon build the context menu is set with gtk_widget_tap_and_hold_setup(). + * + */ void gtk_map_set_context_menu(GtkWidget *widget, GtkMenu *menu) { @@ -2091,6 +2205,11 @@ g_object_unref(priv->menu); priv->menu=NULL; } +/** + * gtk_map_get_menu_latlon: + * + * Get the lat, lon coordinates from where the mouse was clicked to get the context menu. + */ void gtk_map_get_menu_latlon(GtkWidget *widget, gdouble *lat, gdouble *lon) { -- 2.39.5