From 4f383ca3623bca1d2908d4c315b2d9e960d2972f Mon Sep 17 00:00:00 2001 From: Hubert Kowalski Date: Sun, 7 Feb 2021 15:01:33 +0100 Subject: [PATCH] Prepare documentation for release 1.2.0 --- docs/reference/libosmgpsmap-docs.xml | 4 +- docs/reference/libosmgpsmap-sections.txt | 20 --- src/osm-gps-map-image.c | 4 +- src/osm-gps-map-image.h | 63 +++++++++- src/osm-gps-map-layer.h | 52 +++++++- src/osm-gps-map-osd.c | 9 +- src/osm-gps-map-osd.h | 4 +- src/osm-gps-map-point.c | 74 ++++++++++- src/osm-gps-map-point.h | 2 +- src/osm-gps-map-polygon.h | 2 + src/osm-gps-map-source.h | 65 +++++++++- src/osm-gps-map-track.c | 8 +- src/osm-gps-map-track.h | 57 ++++++++- src/osm-gps-map-widget.c | 150 ++++++++++++++++++++--- src/osm-gps-map-widget.h | 4 +- src/osm-gps-map.h | 2 +- 16 files changed, 453 insertions(+), 67 deletions(-) diff --git a/docs/reference/libosmgpsmap-docs.xml b/docs/reference/libosmgpsmap-docs.xml index 72a446c..d933d1b 100644 --- a/docs/reference/libosmgpsmap-docs.xml +++ b/docs/reference/libosmgpsmap-docs.xml @@ -17,12 +17,12 @@ - + Index of all symbols diff --git a/docs/reference/libosmgpsmap-sections.txt b/docs/reference/libosmgpsmap-sections.txt index ba6e268..3e360d4 100644 --- a/docs/reference/libosmgpsmap-sections.txt +++ b/docs/reference/libosmgpsmap-sections.txt @@ -46,30 +46,10 @@ osm_gps_map_layer_remove osm_gps_map_layer_remove_all -
-osm-gps-map-deprecated -OsmGpsMap Deprecated -osm_gps_map_draw_gps -osm_gps_map_clear_gps -osm_gps_map_add_track -osm_gps_map_replace_track -osm_gps_map_clear_tracks -osm_gps_map_add_image -osm_gps_map_add_image_with_alignment -osm_gps_map_remove_image -osm_gps_map_clear_images -osm_gps_map_add_layer -osm_gps_map_get_co_ordinates -osm_gps_map_screen_to_geographic -osm_gps_map_geographic_to_screen -osm_gps_map_set_mapcenter -
-
osm-gps-map-layer OsmGpsMapLayer OsmGpsMapLayer -OsmGpsMapLayerClass osm_gps_map_layer_render osm_gps_map_layer_draw osm_gps_map_layer_busy diff --git a/src/osm-gps-map-image.c b/src/osm-gps-map-image.c index 4459f4e..ff1645b 100644 --- a/src/osm-gps-map-image.c +++ b/src/osm-gps-map-image.c @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -240,7 +240,7 @@ osm_gps_map_image_draw (OsmGpsMapImage *object, cairo_t *cr, GdkRectangle *rect) x = rect->x - xoffset; y = rect->y - yoffset; - cairo_translate(cr, x+(priv->w/2), y+(priv->h/2)); + cairo_translate(cr, x+(priv->w/2), y+(priv->h/2)); cairo_rotate(cr, deg2rad(priv->rotation)); cairo_translate(cr, -(x+(priv->w/2)), -(y+(priv->h/2))); diff --git a/src/osm-gps-map-image.h b/src/osm-gps-map-image.h index f1df21b..351db2b 100644 --- a/src/osm-gps-map-image.h +++ b/src/osm-gps-map-image.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -51,13 +51,74 @@ struct _OsmGpsMapImageClass GObjectClass parent_class; }; +/** + * osm_gps_map_image_get_type: + * + * Get image type + * + * Return value: (element-type GType): The type of the image + * Since: 0.7.0 + **/ GType osm_gps_map_image_get_type (void) G_GNUC_CONST; +/** + * osm_gps_map_image_new: + * + * Create new image + * + * Returns: (transfer full): New image + * Since: 0.7.0 + **/ OsmGpsMapImage *osm_gps_map_image_new (void); +/** + * osm_gps_map_image_draw: + * @object: a #OsmGpsMapImage + * @cr: cairo context + * @rect: (inout): bounding rectangle + * + * Draw image to given cairo context + * + * Since: 0.7.0 + **/ void osm_gps_map_image_draw (OsmGpsMapImage *object, cairo_t *cr, GdkRectangle *rect); +/** + * osm_gps_map_image_get_point: + * @object: a #OsmGpsMapImage + * + * Get image location point + * + * Returns: (transfer none): location point + * Since: 0.7.0 + **/ const OsmGpsMapPoint *osm_gps_map_image_get_point(OsmGpsMapImage *object); +/** + * osm_gps_map_image_get_zorder: + * @object: a #OsmGpsMapImage + * + * Get image z-order + * + * Returns: z-order + * Since: 1.0.0 + **/ gint osm_gps_map_image_get_zorder(OsmGpsMapImage *object); +/** + * osm_gps_map_image_get_rotation: + * @object: a #OsmGpsMapImage + * + * Get image rotation + * + * Returns: rotation + * Since: 1.1.0 + **/ float osm_gps_map_image_get_rotation(OsmGpsMapImage* object); +/** + * osm_gps_map_image_set_rotation: + * @object: a #OsmGpsMapImage + * @rot: image rotation in degrees + * + * Set image rotation + * Since: 1.1.0 + **/ void osm_gps_map_image_set_rotation(OsmGpsMapImage* object, float rot); G_END_DECLS diff --git a/src/osm-gps-map-layer.h b/src/osm-gps-map-layer.h index 366726c..a2d248c 100644 --- a/src/osm-gps-map-layer.h +++ b/src/osm-gps-map-layer.h @@ -12,7 +12,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -51,11 +51,61 @@ struct _OsmGpsMapLayerIface { gboolean (*button_press) (OsmGpsMapLayer *self, OsmGpsMap *map, GdkEventButton *event); }; +/** + * osm_gps_map_layer_get_type: + * + * Get layer type + * + * Return value: (element-type GType): The type of the layer + * Since: 0.6.0 + **/ GType osm_gps_map_layer_get_type (void); +/** + * osm_gps_map_layer_render: + * @self: (in): a #OsmGpsMapLayer object + * @map: (in): a #OsmGpsMap widget + * + * Render layer on map + * + * Since: 0.6.0 + **/ void osm_gps_map_layer_render (OsmGpsMapLayer *self, OsmGpsMap *map); + +/** + * osm_gps_map_layer_draw: + * @self: (in): a #OsmGpsMapLayer object + * @map: (in): a #OsmGpsMap widget + * @cr: (in): a cairo context to draw to + * + * Draw layer on map + * + * Since: 0.6.0 + **/ void osm_gps_map_layer_draw (OsmGpsMapLayer *self, OsmGpsMap *map, cairo_t *cr); + +/** + * osm_gps_map_layer_busy: + * @self: (in): a #OsmGpsMapLayer object + * + * Check whether layer is busy (eg drawing an animation) + * + * Returns: layer busy state + * Since: 0.6.0 + **/ gboolean osm_gps_map_layer_busy (OsmGpsMapLayer *self); + +/** + * osm_gps_map_layer_button_press: + * @self: (in): a #OsmGpsMapLayer object + * @map: (in): a #OsmGpsMap widget + * @event: (in): a #GdkEventButton event + * + * Handle button event + * + * Returns: whether even had been handled + * Since: 0.6.0 + **/ gboolean osm_gps_map_layer_button_press (OsmGpsMapLayer *self, OsmGpsMap *map, GdkEventButton *event); G_END_DECLS diff --git a/src/osm-gps-map-osd.c b/src/osm-gps-map-osd.c index 7e9ec64..04e5297 100644 --- a/src/osm-gps-map-osd.c +++ b/src/osm-gps-map-osd.c @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -459,6 +459,7 @@ osm_gps_map_osd_class_init (OsmGpsMapOsdClass *klass) * OsmGpsMapOsd:show-copyright: * * The show copyright property. + * Since: 1.2.0 */ g_object_class_install_property (object_class, PROP_SHOW_COPYRIGHT, @@ -560,7 +561,7 @@ osm_gps_map_osd_button_press (OsmGpsMapLayer *osd, if(priv->osd_x < 0) mx -= (allocation.width - priv->osd_w); - + if(priv->osd_y < 0) my -= (allocation.height - priv->osd_h); @@ -815,11 +816,11 @@ coordinates_render(OsmGpsMapOsd *self, OsmGpsMap *map) char *latitude = osd_latitude_str(lat); char *longitude = osd_longitude_str(lon); - + int y = OSD_COORDINATES_OFFSET; y = osd_render_centered_text(cr, y, OSD_COORDINATES_W, OSD_COORDINATES_FONT_SIZE, latitude); y = osd_render_centered_text(cr, y, OSD_COORDINATES_W, OSD_COORDINATES_FONT_SIZE, longitude); - + g_free(latitude); g_free(longitude); diff --git a/src/osm-gps-map-osd.h b/src/osm-gps-map-osd.h index 663c1c7..017747c 100644 --- a/src/osm-gps-map-osd.h +++ b/src/osm-gps-map-osd.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -48,7 +48,7 @@ struct _OsmGpsMapOsdClass GObjectClass parent_class; /* vtable */ - + }; GType osm_gps_map_osd_get_type (void); diff --git a/src/osm-gps-map-point.c b/src/osm-gps-map-point.c index 72e32cf..e50d8f4 100644 --- a/src/osm-gps-map-point.c +++ b/src/osm-gps-map-point.c @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -23,7 +23,7 @@ * @stability: Stable * @include: osm-gps-map.h * - * #OsmGpsMapPoint describes a geographic location (latitude, longitude). + * #OsmGpsMapPoint describes a geographic location (latitude, longitude). * Helper functions exist to create such a point from either radian co-ordinates * (osm_gps_map_point_new_radians()) or degrees (osm_gps_map_new_degrees()). **/ @@ -43,6 +43,16 @@ osm_gps_map_point_get_type (void) return our_type; } +/** + * osm_gps_map_point_new_degrees: + * @lat: (in): latitude in degrees + * @lon: (in): longtitude in degrees + * + * Create point with specified params + * + * Returns: (transfer full): new point object + * Since: 0.7.0 + **/ OsmGpsMapPoint * osm_gps_map_point_new_degrees(float lat, float lon) { @@ -53,6 +63,16 @@ osm_gps_map_point_new_degrees(float lat, float lon) return p; } +/** + * osm_gps_map_point_new_radians: + * @rlat: (in): latitude in radians + * @rlon: (in): longtitude in radians + * + * Create point with specified params + * + * Returns: (transfer full): new point object + * Since: 0.7.0 + **/ OsmGpsMapPoint * osm_gps_map_point_new_radians(float rlat, float rlon) { @@ -65,7 +85,13 @@ osm_gps_map_point_new_radians(float rlat, float rlon) /** * osm_gps_map_point_new_degrees_with_user_data: + * @lat: (in): latitude in degrees + * @lon: (in): longtitude in degrees + * @user_data: (in): user data * + * Create point with specified params + * + * Returns: (transfer full): new point object * Since: 1.2.0 **/ OsmGpsMapPoint * @@ -84,6 +110,9 @@ osm_gps_map_point_new_degrees_with_user_data(float lat, float lon, gpointer user * @rlon: (in): longtitude in radians * @user_data: (in): user data * + * Create point with specified params + * + * Returns: (transfer full): new point object * Since: 1.2.0 **/ OsmGpsMapPoint * @@ -103,7 +132,8 @@ osm_gps_map_point_new_radians_with_user_data(float rlat, float rlon, gpointer us * @lon: (out): longitude in degrees * * Returns the lagitude and longitude in degrees. - * of the current window, i.e the top left and bottom right corners. + * + * Since: 0.7.0 **/ void osm_gps_map_point_get_degrees(OsmGpsMapPoint *point, float *lat, float *lon) @@ -114,12 +144,13 @@ osm_gps_map_point_get_degrees(OsmGpsMapPoint *point, float *lat, float *lon) /** * osm_gps_map_point_get_radians: - * @point: The point ( latitude and longitude in radian ) + * @point: The #OsmGpsMapPoint point ( latitude and longitude in radian ) * @rlat: (out): latitude in radians * @rlon: (out): longitude in radians * * Returns the lagitude and longitude in radians. - * of the current window, i.e the top left and bottom right corners. + * + * Since: 0.7.0 **/ void osm_gps_map_point_get_radians(OsmGpsMapPoint *point, float *rlat, float *rlon) @@ -128,6 +159,16 @@ osm_gps_map_point_get_radians(OsmGpsMapPoint *point, float *rlat, float *rlon) *rlon = point->rlon; } +/** + * osm_gps_map_point_set_degrees: + * @point: The #OsmGpsMapPoint point ( latitude and longitude in radian ) + * @lat: (in): latitude in degrees + * @lon: (in): longitude in degrees + * + * Sets the lagitude and longitude in degrees. + * + * Since: 0.7.0 + **/ void osm_gps_map_point_set_degrees(OsmGpsMapPoint *point, float lat, float lon) { @@ -135,6 +176,16 @@ osm_gps_map_point_set_degrees(OsmGpsMapPoint *point, float lat, float lon) point->rlon = deg2rad(lon); } +/** + * osm_gps_map_point_set_radians: + * @point: The #OsmGpsMapPoint point ( latitude and longitude in radian ) + * @rlat: (in): latitude in radians + * @rlon: (in): longitude in radians + * + * Sets the lagitude and longitude in radians. + * + * Since: 0.7.0 + **/ void osm_gps_map_point_set_radians(OsmGpsMapPoint *point, float rlat, float rlon) { @@ -144,6 +195,9 @@ osm_gps_map_point_set_radians(OsmGpsMapPoint *point, float rlat, float rlon) /** * osm_gps_map_point_get_user_data: + * @point: The #OsmGpsMapPoint point + * + * Get user data stored in point * * Returns: (transfer none): The #OsmGpsMapPoint user data * Since: 1.2.0 @@ -156,8 +210,11 @@ osm_gps_map_point_get_user_data(OsmGpsMapPoint *point) /** * osm_gps_map_point_set_user_data: + * @point: The #OsmGpsMapPoint point * @user_data: (in): user data * + * Store user data in point + * * Since: 1.2.0 **/ void @@ -168,7 +225,11 @@ osm_gps_map_point_set_user_data(OsmGpsMapPoint *point, gpointer user_data) /** * osm_gps_map_point_copy: + * @point: (in): a #OsmGpsMapPoint object + * + * Create a copy of a point * + * Returns: (transfer full): Copied point * Since: 0.7.2 */ OsmGpsMapPoint * @@ -182,6 +243,9 @@ osm_gps_map_point_copy (const OsmGpsMapPoint *point) /** * osm_gps_map_point_free: + * @point: a #OsmGpsMapPoint object + * + * Free point object * * Since: 0.7.2 */ diff --git a/src/osm-gps-map-point.h b/src/osm-gps-map-point.h index fcbfebd..6a50a7e 100644 --- a/src/osm-gps-map-point.h +++ b/src/osm-gps-map-point.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the diff --git a/src/osm-gps-map-polygon.h b/src/osm-gps-map-polygon.h index 62a3817..727b92d 100644 --- a/src/osm-gps-map-polygon.h +++ b/src/osm-gps-map-polygon.h @@ -58,6 +58,8 @@ OsmGpsMapPolygon* osm_gps_map_polygon_new (void); * osm_gps_map_polygon_get_track: * @poly: a #OsmGpsMapPolygon * + * Get track from the polygon + * * Returns: (transfer none): The #OsmGpsMapTrack of the polygon **/ OsmGpsMapTrack* osm_gps_map_polygon_get_track(OsmGpsMapPolygon* poly); diff --git a/src/osm-gps-map-source.h b/src/osm-gps-map-source.h index 1e20ba7..979c57d 100644 --- a/src/osm-gps-map-source.h +++ b/src/osm-gps-map-source.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -43,12 +43,75 @@ typedef enum { OSM_GPS_MAP_SOURCE_LAST } OsmGpsMapSource_t; +/** + * osm_gps_map_source_get_friendly_name: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get friendly name for source + * + * Returns: Nice printable source name + * Since: 0.7.0 + **/ const char* osm_gps_map_source_get_friendly_name (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_get_copyright: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get copyright information for the source + * + * Returns: Source copyright information + * Since: 1.2.0 + **/ const char* osm_gps_map_source_get_copyright (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_get_repo_uri: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get repository URI address for the source + * + * Returns: Source repo URI + * Since: 0.7.0 + **/ const char* osm_gps_map_source_get_repo_uri (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_get_image_format: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get tile image format for the source + * + * Returns: source tile image format + * Since: 0.7.0 + **/ const char* osm_gps_map_source_get_image_format (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_get_min_zoom: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get minimum zoom level for the source + * + * Returns: source minimum zoom level + * Since: 0.7.0 + **/ int osm_gps_map_source_get_min_zoom (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_get_max_zoom: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Get maximum zoom level for the source + * + * Returns: source maximum zoom level + * Since: 0.7.0 + **/ int osm_gps_map_source_get_max_zoom (OsmGpsMapSource_t source); +/** + * osm_gps_map_source_is_valid: + * @source: (in): a #OsmGpsMapSource_t source id + * + * Check whether source is considered valid + * + * Returns: Validity of the source (whether repo uri is not null) + * Since: 0.7.0 + **/ gboolean osm_gps_map_source_is_valid (OsmGpsMapSource_t source); G_END_DECLS diff --git a/src/osm-gps-map-track.c b/src/osm-gps-map-track.c index 33e4123..dbdc7f4 100644 --- a/src/osm-gps-map-track.c +++ b/src/osm-gps-map-track.c @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -335,7 +335,7 @@ osm_gps_map_track_get_points (OsmGpsMapTrack *track) return track->priv->track; } -void +void osm_gps_map_track_set_color (OsmGpsMapTrack *track, GdkRGBA *color) { g_return_if_fail (OSM_GPS_MAP_IS_TRACK (track)); @@ -360,14 +360,14 @@ osm_gps_map_track_get_length(OsmGpsMapTrack* track) double ret = 0; OsmGpsMapPoint* point_a = NULL; OsmGpsMapPoint* point_b = NULL; - + while(points) { point_a = point_b; point_b = points->data; if(point_a) { - ret += acos(sin(point_a->rlat)*sin(point_b->rlat) + ret += acos(sin(point_a->rlat)*sin(point_b->rlat) + cos(point_a->rlat)*cos(point_b->rlat)*cos(point_b->rlon-point_a->rlon)) * 6371109; //the mean raduis of earth } points = points->next; diff --git a/src/osm-gps-map-track.h b/src/osm-gps-map-track.h index dc6de1e..1195df3 100644 --- a/src/osm-gps-map-track.h +++ b/src/osm-gps-map-track.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -54,17 +54,28 @@ struct _OsmGpsMapTrackClass /** * osm_gps_map_track_get_type: * - * Return value: (element-type GType): The type of the track + * Get track type * + * Return value: (element-type GType): The type of the track * Since: 0.7.0 **/ GType osm_gps_map_track_get_type (void) G_GNUC_CONST; +/** + * osm_gps_map_track_new: + * + * Create new track + * + * Returns: (transfer full): New track + * Since: 0.7.0 + **/ OsmGpsMapTrack * osm_gps_map_track_new (void); /** * osm_gps_map_track_add_point: * @track: (inout): a #OsmGpsMapTrack - * @point: (in): point to add + * @point: (in): a #OsmGpsMapPoint point to add + * + * Add a point to track * * Since: 0.7.0 **/ @@ -73,12 +84,31 @@ void osm_gps_map_track_add_point (OsmGpsMapTrack *track, cons * osm_gps_map_track_get_points: * @track: (in): a #OsmGpsMapTrack * - * Returns: (element-type OsmGpsMapPoint) (transfer none): list of #OsmGpsMapPoint + * Get list of points in the track * + * Returns: (element-type OsmGpsMapPoint) (transfer none): list of #OsmGpsMapPoint * Since: 0.7.0 **/ GSList * osm_gps_map_track_get_points (OsmGpsMapTrack *track); +/** + * osm_gps_map_track_set_color: + * @track: (in): a #OsmGpsMapTrack + * @color: (in): new track color + * + * Set track color + * + * Since: 1.1.0 + **/ void osm_gps_map_track_set_color (OsmGpsMapTrack *track, GdkRGBA *color); +/** + * osm_gps_map_track_get_color: + * @track: (in): a #OsmGpsMapTrack + * @color: (out caller-allocates): track color + * + * Get track color + * + * Since: 0.7.0 + **/ void osm_gps_map_track_get_color (OsmGpsMapTrack *track, GdkRGBA *color); /** @@ -86,6 +116,9 @@ void osm_gps_map_track_get_color (OsmGpsMapTrack *track, GdkR * @track: (in): a #OsmGpsMapTrack * @pos: Position of the point to remove * + * Remove track point at @pos position in point list + * + * Since: 1.1.0 **/ void osm_gps_map_track_remove_point(OsmGpsMapTrack* track, int pos); @@ -93,7 +126,10 @@ void osm_gps_map_track_remove_point(OsmGpsMapTrack* track, int po * osm_gps_map_track_n_points: * @track: a #OsmGpsMapTrack * - * Returns: the number of points of the track. + * Get number of points in the track + * + * Returns: the number of points in the track. + * Since: 1.1.0 **/ int osm_gps_map_track_n_points(OsmGpsMapTrack* track); @@ -103,6 +139,9 @@ int osm_gps_map_track_n_points(OsmGpsMapTrack* track); * @np: a #OsmGpsMapPoint * @pos: Position for the point * + * Instert point @np at given postition @pos + * + * Since: 1.1.0 **/ void osm_gps_map_track_insert_point(OsmGpsMapTrack* track, OsmGpsMapPoint* np, int pos); @@ -111,7 +150,10 @@ void osm_gps_map_track_insert_point(OsmGpsMapTrack* track, OsmGps * @track: a #OsmGpsMapTrack * @pos: Position of the point to get * - * Returns: (transfer none): a #OsmGpsMapPoint + * Get a #OsmGpsMapPoint point at @pos of given track + * + * Returns: (transfer none): a #OsmGpsMapPoint + * Since: 1.1.0 **/ OsmGpsMapPoint* osm_gps_map_track_get_point(OsmGpsMapTrack* track, int pos); @@ -119,7 +161,10 @@ OsmGpsMapPoint* osm_gps_map_track_get_point(OsmGpsMapTrack* track, int pos); * osm_gps_map_track_get_length: * @track: (in): a #OsmGpsMapTrack * + * Get track length in meters + * * Returns: the length of the track in meters. + * Since: 1.1.0 **/ double osm_gps_map_track_get_length(OsmGpsMapTrack* track); diff --git a/src/osm-gps-map-widget.c b/src/osm-gps-map-widget.c index d81739f..91f7dc2 100644 --- a/src/osm-gps-map-widget.c +++ b/src/osm-gps-map-widget.c @@ -2674,7 +2674,7 @@ osm_gps_map_class_init (OsmGpsMapClass *klass) * The default user-agent for downloading tiles from the #OsmGpsMap:map-source * is "libosmgpsmap/VERSION". The value of #OsmGpsMap:user-agent will be * appended to it. - * + * * Since: 1.2.0 **/ g_object_class_install_property (object_class, @@ -2925,6 +2925,11 @@ osm_gps_map_class_init (OsmGpsMapClass *klass) /** * osm_gps_map_download_maps: + * @map: a #OsmGpsMap widget + * @pt1: (in): nort west corner + * @pt2: (in): south east corner + * @zoom_start: (in): start of zoom range + * @zoom_end: (in): end of zoom range * * Downloads all tiles over the supplied zoom range in the rectangular * region specified by pt1 (north west corner) to pt2 (south east corner) @@ -2989,6 +2994,7 @@ cancel_message (char *key, SoupMessage *value, SoupSession *user_data) /** * osm_gps_map_download_cancel_all: + * @map: a #OsmGpsMap widget * * Cancels all tiles currently being downloaded. Typically used if you wish to * cacel a large number of tiles queued using osm_gps_map_download_maps() @@ -3004,6 +3010,7 @@ osm_gps_map_download_cancel_all (OsmGpsMap *map) /** * osm_gps_map_get_bbox: + * @map: a #OsmGpsMap widget * @pt1: (out): point to be filled with the top left location * @pt2: (out): point to be filled with the bottom right location * @@ -3027,7 +3034,15 @@ osm_gps_map_get_bbox (OsmGpsMap *map, OsmGpsMapPoint *pt1, OsmGpsMapPoint *pt2) /** * osm_gps_map_zoom_fit_bbox: + * @map: a #OsmGpsMap widget + * @latitude1: (in): latitude of 1st point in degrees + * @latitude2: (in): latitude of 2nd point in degrees + * @longitude1: (in): longtitude of 1st point in degrees + * @longitude2: (in): longtitude of 2nd point in degrees + * * Zoom and center the map so that both points fit inside the window. + * + * Since: 1.1.0 **/ void osm_gps_map_zoom_fit_bbox (OsmGpsMap *map, float latitude1, float latitude2, float longitude1, float longitude2) @@ -3036,12 +3051,17 @@ osm_gps_map_zoom_fit_bbox (OsmGpsMap *map, float latitude1, float latitude2, flo int zoom; gtk_widget_get_allocation (GTK_WIDGET (map), &allocation); zoom = latlon2zoom (allocation.height, allocation.width, deg2rad(latitude1), deg2rad(latitude2), deg2rad(longitude1), deg2rad(longitude2)); - osm_gps_map_set_center (map, (latitude1 + latitude2) / 2, (longitude1 + longitude2) / 2); - osm_gps_map_set_zoom (map, zoom); + osm_gps_map_set_center_and_zoom (map, (latitude1 + latitude2) / 2, (longitude1 + longitude2) / 2, zoom); } /** * osm_gps_map_set_center_and_zoom: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @zoom: desired zoom level + * + * Set map center and desired zoom level * * Since: 0.7.0 **/ @@ -3053,6 +3073,11 @@ void osm_gps_map_set_center_and_zoom (OsmGpsMap *map, float latitude, float long /** * osm_gps_map_set_center: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * + * Set map center, does not change zoom level * **/ void @@ -3084,6 +3109,10 @@ osm_gps_map_set_center (OsmGpsMap *map, float latitude, float longitude) /** * osm_gps_map_set_zoom_offset: + * @map: a #OsmGpsMap widget + * @zoom_offset: tile zoom offset + * + * Set tile zoom offset * **/ void @@ -3103,6 +3132,12 @@ osm_gps_map_set_zoom_offset (OsmGpsMap *map, int zoom_offset) /** * osm_gps_map_set_zoom: + * @map: a #OsmGpsMap widget + * @zoom: (in): Desired zoom level + * + * Set map zoom to the desired zoom level + * + * Returns: zoom level * **/ int @@ -3136,6 +3171,11 @@ osm_gps_map_set_zoom (OsmGpsMap *map, int zoom) /** * osm_gps_map_zoom_in: + * @map: a #OsmGpsMap widget + * + * Zoom in by 1 step + * + * Returns: zoom level * **/ int @@ -3147,6 +3187,11 @@ osm_gps_map_zoom_in (OsmGpsMap *map) /** * osm_gps_map_zoom_out: + * @map: a #OsmGpsMap widget + * + * Zoom out by 1 step + * + * Returns: zoom level * **/ int @@ -3175,9 +3220,9 @@ osm_gps_map_new (void) /** * osm_gps_map_scroll: - * @map: - * @dx: - * @dy: + * @map: a #OsmGpsMap widget + * @dx: pixels to scroll in NS (positive: scroll nort, negative: scroll south) + * @dy: pixels to scroll in EW (positive: scroll east, negative: scroll west) * * Scrolls the map by @dx, @dy pixels (positive north, east) * @@ -3199,7 +3244,9 @@ osm_gps_map_scroll (OsmGpsMap *map, gint dx, gint dy) /** * osm_gps_map_get_scale: - * @map: + * @map: a #OsmGpsMap widget + * + * Get the scale of the map at the center, in meters/pixel. * * Returns: the scale of the map at the center, in meters/pixel. * @@ -3218,7 +3265,7 @@ osm_gps_map_get_scale (OsmGpsMap *map) /** * osm_gps_map_get_default_cache_directory: * - * Returns: the default cache directory for the library, that is the base + * Returns (transfer full): the default cache directory for the library, that is the base * directory to which the full cache path is appended. If * #OsmGpsMap:tile-cache-base is omitted from the constructor then this value * is used. @@ -3235,8 +3282,9 @@ osm_gps_map_get_default_cache_directory (void) /** * osm_gps_map_set_keyboard_shortcut: + * @map: a #OsmGpsMap widget * @key: a #OsmGpsMapKey_t - * @keyval: + * @keyval: a keyval to bind * * Associates a keyboard shortcut with the supplied @keyval * (as returned by #gdk_keyval_from_name or simiar). The action given in @key @@ -3256,6 +3304,10 @@ osm_gps_map_set_keyboard_shortcut (OsmGpsMap *map, OsmGpsMapKey_t key, guint key /** * osm_gps_map_track_add: + * @map: a #OsmGpsMap widget + * @track: a @OsmGpsMapTrack object + * + * Add a track to map * * Since: 0.7.0 **/ @@ -3279,6 +3331,9 @@ osm_gps_map_track_add (OsmGpsMap *map, OsmGpsMapTrack *track) /** * osm_gps_map_track_remove_all: + * @map: a #OsmGpsMap widget + * + * Remove all tracks * * Since: 0.7.0 **/ @@ -3293,6 +3348,10 @@ osm_gps_map_track_remove_all (OsmGpsMap *map) /** * osm_gps_map_track_remove: + * @map: a #OsmGpsMap widget + * @track: a #OsmGpsMapTrack object + * + * Remove given track from map * * Since: 0.7.0 **/ @@ -3354,6 +3413,9 @@ osm_gps_map_polygon_remove(OsmGpsMap *map, OsmGpsMapPolygon *poly) /** * osm_gps_map_gps_clear: + * @map: a #OsmGpsMap widget + * + * Clear GPS track history * * Since: 0.7.0 **/ @@ -3376,6 +3438,9 @@ osm_gps_map_gps_clear (OsmGpsMap *map) /** * osm_gps_map_gps_get_track: + * @map: a #OsmGpsMap widget + * + * Get internal GPS track history * * Returns: (transfer none): The #OsmGpsMapTrack of the internal GPS track, * i.e. that which is modified when calling osm_gps_map_gps_add(). You must @@ -3391,9 +3456,13 @@ osm_gps_map_gps_get_track (OsmGpsMap *map) /** * osm_gps_map_gps_add: - * @latitude: degrees - * @longitude: degrees - * @heading: degrees or #OSM_GPS_MAP_INVALID to disable showing heading + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @heading: GPS degrees or #OSM_GPS_MAP_INVALID to disable showing heading + * + * Set current GPS point to given lat/lon point with given heading. + * If record-trip-history is set, add point to trip history * * Since: 0.7.0 **/ @@ -3425,6 +3494,12 @@ osm_gps_map_gps_add (OsmGpsMap *map, float latitude, float longitude, float head /** * osm_gps_map_image_add: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @image: (in): Image pixbuf + * + * Creates @OsmGpsMapImage with given params and adds it to map images * * Returns: (transfer full): A #OsmGpsMapImage representing the added pixbuf * Since: 0.7.0 @@ -3437,6 +3512,13 @@ osm_gps_map_image_add (OsmGpsMap *map, float latitude, float longitude, GdkPixbu /** * osm_gps_map_image_add_z: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @image: (in): Image pixbuf + * @zorder: z-order of image + * + * Creates @OsmGpsMapImage with given params and adds it to map images * * Returns: (transfer full): A #OsmGpsMapImage representing the added pixbuf * Since: 0.7.4 @@ -3455,6 +3537,14 @@ on_image_changed (OsmGpsMapImage *image, GParamSpec *pspec, OsmGpsMap *map) /** * osm_gps_map_image_add_with_alignment: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @image: (in): Image pixbuf + * @xalign: x-align of image + * @yalign: y-align of image + * + * Creates @OsmGpsMapImage with given params and adds it to map images * * Returns: (transfer full): A #OsmGpsMapImage representing the added pixbuf * Since: 0.7.0 @@ -3476,6 +3566,15 @@ osm_gps_map_image_z_compare(gconstpointer item1, gconstpointer item2) /** * osm_gps_map_image_add_with_alignment_z: + * @map: a #OsmGpsMap widget + * @latitude: latitude in degrees + * @longitude: longitude in degrees + * @image: (in): Image pixbuf + * @xalign: x-align of image + * @yalign: y-align of image + * @zorder: z-order of image + * + * Creates @OsmGpsMapImage with given params and adds it to map images * * Returns: (transfer full): A #OsmGpsMapImage representing the added pixbuf * Since: 0.7.4 @@ -3504,6 +3603,12 @@ osm_gps_map_image_add_with_alignment_z (OsmGpsMap *map, float latitude, float lo /** * osm_gps_map_image_remove: + * @map: a #OsmGpsMap widget + * @image: (in): a @OsmGpsMapImage to remove + * + * Remove image from list of images + * + * Returns: true if image was on list of images * * Since: 0.7.0 **/ @@ -3522,6 +3627,9 @@ osm_gps_map_image_remove (OsmGpsMap *map, OsmGpsMapImage *image) /** * osm_gps_map_image_remove_all: + * @map: a #OsmGpsMap widget + * + * Remove all images from map * * Since: 0.7.0 **/ @@ -3536,8 +3644,11 @@ osm_gps_map_image_remove_all (OsmGpsMap *map) /** * osm_gps_map_layer_add: + * @map: a #OsmGpsMap widget * @layer: a #OsmGpsMapLayer object * + * Add layer to map + * * Since: 0.7.0 **/ void @@ -3552,8 +3663,12 @@ osm_gps_map_layer_add (OsmGpsMap *map, OsmGpsMapLayer *layer) /** * osm_gps_map_layer_remove: + * @map: a #OsmGpsMap widget * @layer: a #OsmGpsMapLayer object * + * Remove layer from map + * + * Returns: whether layer was found and removed * Since: 0.7.0 **/ gboolean @@ -3571,6 +3686,9 @@ osm_gps_map_layer_remove (OsmGpsMap *map, OsmGpsMapLayer *layer) /** * osm_gps_map_layer_remove_all: + * @map: a #OsmGpsMap widget + * + * Remove all layers from map * * Since: 0.7.0 **/ @@ -3585,7 +3703,7 @@ osm_gps_map_layer_remove_all (OsmGpsMap *map) /** * osm_gps_map_convert_screen_to_geographic: - * @map: + * @map: a #OsmGpsMap widget * @pixel_x: pixel location on map, x axis * @pixel_y: pixel location on map, y axis * @pt: (out): location @@ -3614,7 +3732,7 @@ osm_gps_map_convert_screen_to_geographic(OsmGpsMap *map, gint pixel_x, gint pixe /** * osm_gps_map_convert_geographic_to_screen: - * @map: + * @map: a #OsmGpsMap widget * @pt: location * @pixel_x: (out): pixel location on map, x axis * @pixel_y: (out): pixel location on map, y axis @@ -3645,12 +3763,14 @@ osm_gps_map_convert_geographic_to_screen(OsmGpsMap *map, OsmGpsMapPoint *pt, gin /** * osm_gps_map_get_event_location: - * @map: + * @map: a #OsmGpsMap widget * @event: A #GtkEventButton that occured on the map * * A convenience function for getting the geographic location of events, * such as mouse clicks, on the map * + * Free returned point with g_free + * * Returns: (transfer full): The point on the globe corresponding to the click * Since: 0.7.0 **/ diff --git a/src/osm-gps-map-widget.h b/src/osm-gps-map-widget.h index 76b28bb..d75c831 100644 --- a/src/osm-gps-map-widget.h +++ b/src/osm-gps-map-widget.h @@ -9,7 +9,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -100,7 +100,7 @@ void osm_gps_map_track_remove_all (OsmGpsMap *map); gboolean osm_gps_map_track_remove (OsmGpsMap *map, OsmGpsMapTrack *track); void osm_gps_map_polygon_add (OsmGpsMap *map, OsmGpsMapPolygon *poly); void osm_gps_map_polygon_remove_all (OsmGpsMap *map); -gboolean osm_gps_map_polygon_remove (OsmGpsMap *map, OsmGpsMapPolygon *poly); +gboolean osm_gps_map_polygon_remove (OsmGpsMap *map, OsmGpsMapPolygon *poly); void osm_gps_map_gps_add (OsmGpsMap *map, float latitude, float longitude, float heading); void osm_gps_map_gps_clear (OsmGpsMap *map); OsmGpsMapTrack *osm_gps_map_gps_get_track (OsmGpsMap *map); diff --git a/src/osm-gps-map.h b/src/osm-gps-map.h index 5023270..f7c76a4 100644 --- a/src/osm-gps-map.h +++ b/src/osm-gps-map.h @@ -7,7 +7,7 @@ * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. - * + * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the