ChamplainView

## ChamplainView ChamplainView — A ClutterActor to display maps |

## Synopsis

    enum                ChamplainScrollMode;
    enum                ChamplainUnit;
    struct              ChamplainView;
    ClutterActor *      champlain_view_new                  (void);
    void                champlain_view_center_on            (ChamplainView *view,
                                                             gdouble latitude,
                                                             gdouble longitude);
    void                champlain_view_go_to                (ChamplainView *view,
                                                             gdouble latitude,
                                                             gdouble longitude);
    void                champlain_view_stop_go_to           (ChamplainView *view);
    void                champlain_view_zoom_in              (ChamplainView *view);
    void                champlain_view_zoom_out             (ChamplainView *view);
    void                champlain_view_ensure_visible       (ChamplainView *view,
                                                             gdouble lat1,
                                                             gdouble lon1,
                                                             gdouble lat2,
                                                             gdouble lon2,
                                                             gboolean animate);
    void                champlain_view_ensure_markers_visible
                                                            (ChamplainView *view,
                                                             ChamplainBaseMarker *markers[],
                                                             gboolean animate);
    void                champlain_view_set_min_zoom_level   (ChamplainView *view,
                                                             gint zoom_level);
    gint                champlain_view_get_min_zoom_level   (ChamplainView *view);
    void                champlain_view_set_max_zoom_level   (ChamplainView *view,
                                                             gint zoom_level);
    gint                champlain_view_get_max_zoom_level   (ChamplainView *view);
    void                champlain_view_set_map_source       (ChamplainView *view,
                                                             ChamplainMapSource *map_source);
    ChamplainMapSource * champlain_view_get_map_source      (ChamplainView *view);
    void                champlain_view_set_size             (ChamplainView *view,
                                                             guint width,
                                                             guint height);
    void                champlain_view_set_decel_rate       (ChamplainView *view,
                                                             gdouble rate);
    gdouble             champlain_view_get_decel_rate       (ChamplainView *view);
    void                champlain_view_set_scroll_mode      (ChamplainView *view,
                                                             ChamplainScrollMode mode);
    ChamplainScrollMode  champlain_view_get_scroll_mode     (ChamplainView *view);
    void                champlain_view_set_keep_center_on_resize
                                                            (ChamplainView *view,
                                                             gboolean value);
    gboolean            champlain_view_get_keep_center_on_resize
                                                            (ChamplainView *view);
    void                champlain_view_set_show_license     (ChamplainView *view,
                                                             gboolean value);
    gboolean            champlain_view_get_show_license     (ChamplainView *view);
    void                champlain_view_set_zoom_level       (ChamplainView *view,
                                                             gint zoom_level);
    gint                champlain_view_get_zoom_level       (ChamplainView *view);
    void                champlain_view_set_zoom_on_double_click
                                                            (ChamplainView *view,
                                                             gboolean value);
    gboolean            champlain_view_get_zoom_on_double_click
                                                            (ChamplainView *view);
    void                champlain_view_set_license_text     (ChamplainView *view,
                                                             const gchar *text);
    const gchar *       champlain_view_get_license_text     (ChamplainView *view);
    void                champlain_view_set_max_scale_width  (ChamplainView *view,
                                                             guint value);
    guint               champlain_view_get_max_scale_width  (ChamplainView *view);
    void                champlain_view_set_scale_unit       (ChamplainView *view,
                                                             ChamplainUnit unit);
    ChamplainUnit       champlain_view_get_scale_unit       (ChamplainView *view);
    void                champlain_view_set_show_scale       (ChamplainView *view,
                                                             gboolean value);
    gboolean            champlain_view_get_show_scale       (ChamplainView *view);
    void                champlain_view_add_layer            (ChamplainView *view,
                                                             ChamplainLayer *layer);
    void                champlain_view_remove_layer         (ChamplainView *view,
                                                             ChamplainLayer *layer);
    gboolean            champlain_view_get_coords_from_event
                                                            (ChamplainView *view,
                                                             ClutterEvent *event,
                                                             gdouble *lat,
                                                             gdouble *lon);
    gboolean            champlain_view_get_coords_at        (ChamplainView *view,
                                                             guint x,
                                                             guint y,
                                                             gdouble *lat,
                                                             gdouble *lon);
    void                champlain_view_add_polygon          (ChamplainView *view,
                                                             ChamplainPolygon *polygon);
    void                champlain_view_remove_polygon       (ChamplainView *view,
                                                             ChamplainPolygon *polygon);
    void                champlain_view_reload_tiles         (ChamplainView *view);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterGroup
                         +----ChamplainView

## Implemented Interfaces

ChamplainView implements ClutterScriptable, ClutterAnimatable, AtkImplementorIface and ClutterContainer.

## Properties

      "decel-rate"               gdouble               : Read / Write
      "keep-center-on-resize"    gboolean              : Read / Write
      "latitude"                 gdouble               : Read / Write
      "license-text"             gchar*                : Read / Write
      "longitude"                gdouble               : Read / Write
      "map-source"               ChamplainMapSource*   : Read / Write
      "max-scale-width"          guint                 : Read / Write
      "max-zoom-level"           gint                  : Read / Write
      "min-zoom-level"           gint                  : Read / Write
      "scale-unit"               ChamplainUnit         : Read / Write
      "scroll-mode"              ChamplainScrollMode   : Read / Write
      "show-license"             gboolean              : Read / Write
      "show-scale"               gboolean              : Read / Write
      "state"                    ChamplainState        : Read
      "zoom-level"               gint                  : Read / Write
      "zoom-on-double-click"     gboolean              : Read / Write

## Signals

      "animation-completed"                            : Has Details

## Description

The ChamplainView is a ClutterActor to display maps. It supports two modes of scrolling:

- Push: the normal behavior where the maps doesn't move after the user stopped scrolling;

- Kinetic: the iPhone-like behavior where the maps decelerate after the user stopped scrolling.

You can use the same ChamplainView to display many types of maps. In Champlain they are called map sources. You can change the map-source property at anytime to replace the current displayed map.

The maps are downloaded from Internet from open maps sources (like OpenStreetMap). Maps are divided in tiles for each zoom level. When a tile is requested, ChamplainView will first check if it is in cache (in the user's cache dir under champlain). If an error occurs during download, an error tile will be displayed.

The button-press-event and button-release-event signals are emitted each time a mouse button is pressed on the `view`. Coordinates can be converted with champlain_view_get_coords_from_event.

## Details

### enum ChamplainScrollMode

    typedef enum
    {
      CHAMPLAIN_SCROLL_MODE_PUSH,
      CHAMPLAIN_SCROLL_MODE_KINETIC
    } ChamplainScrollMode;

Type of scrolling.

`CHAMPLAIN_SCROLL_MODE_PUSH` | Non-kinetic scrolling
`CHAMPLAIN_SCROLL_MODE_KINETIC` | Kinetic scrolling

### enum ChamplainUnit

    typedef enum
    {
      CHAMPLAIN_UNIT_KM,
      CHAMPLAIN_UNIT_MILES,
    } ChamplainUnit;

Units used by the scale.

`CHAMPLAIN_UNIT_KM` | kilometers
`CHAMPLAIN_UNIT_MILES` | miles

### struct ChamplainView

    struct ChamplainView;

### champlain_view_new ()

    ClutterActor *      champlain_view_new                  (void);

Creates an instance of ChamplainView.

Returns : | a new ChamplainView ready to be used as a ClutterActor.

Since 0.4

### champlain_view_center_on ()

    void                champlain_view_center_on            (ChamplainView *view,
                                                             gdouble latitude,
                                                             gdouble longitude);

Centers the map on these coordinates.

`view` : | a ChamplainView
`latitude` : | the longitude to center the map at
`longitude` : | the longitude to center the map at

Since 0.1

### champlain_view_go_to ()

    void                champlain_view_go_to                (ChamplainView *view,
                                                             gdouble latitude,
                                                             gdouble longitude);

Move from the current position to these coordinates. All tiles in the intermediate view WILL be loaded!

`view` : | a ChamplainView
`latitude` : | the longitude to center the map at
`longitude` : | the longitude to center the map at

Since 0.4

### champlain_view_stop_go_to ()

    void                champlain_view_stop_go_to           (ChamplainView *view);

Stop the go to animation. The view will stay where it was when the animation was stopped.

`view` : | a ChamplainView

Since 0.4

### champlain_view_zoom_in ()

    void                champlain_view_zoom_in              (ChamplainView *view);

Zoom in the map by one level.

`view` : | a ChamplainView

Since 0.1

### champlain_view_zoom_out ()

    void                champlain_view_zoom_out             (ChamplainView *view);

Zoom out the map by one level.

`view` : | a ChamplainView

Since 0.1

### champlain_view_ensure_visible ()

    void                champlain_view_ensure_visible       (ChamplainView *view,
                                                             gdouble lat1,
                                                             gdouble lon1,
                                                             gdouble lat2,
                                                             gdouble lon2,
                                                             gboolean animate);

Changes the map's zoom level and center to make sure the two given positions are visible

`view` : | a ChamplainView
`lat1` : | the latitude of position 1
`lon1` : | the longitude of position 1
`lat2` : | the latitude of position 2
`lon2` : | the longitude of position 2
`animate` : | a gboolean

Since 0.4

### champlain_view_ensure_markers_visible ()

    void                champlain_view_ensure_markers_visible
                                                            (ChamplainView *view,
                                                             ChamplainBaseMarker *markers[],
                                                             gboolean animate);

Changes the map's zoom level and center to make sure those markers are visible.

FIXME: This doesn't take into account the marker's actor size yet

`view` : | a ChamplainView
`markers` : | a NULL terminated array of ChamplainMarker elements. [array zero-terminated=1]
`animate` : | a gboolean

Since 0.4

### champlain_view_set_min_zoom_level ()

    void                champlain_view_set_min_zoom_level   (ChamplainView *view,
                                                             gint zoom_level);

Changes the lowest allowed zoom level

`view` : | a ChamplainView
`zoom_level` : | a gint

Since 0.4

### champlain_view_get_min_zoom_level ()

    gint                champlain_view_get_min_zoom_level   (ChamplainView *view);

Gets the view's minimal allowed zoom level.

`view` : | The view
Returns : | the view's minimal allowed zoom level.

Since 0.4

### champlain_view_set_max_zoom_level ()

    void                champlain_view_set_max_zoom_level   (ChamplainView *view,
                                                             gint zoom_level);

Changes the highest allowed zoom level

`view` : | a ChamplainView
`zoom_level` : | a gint

Since 0.4

### champlain_view_get_max_zoom_level ()

    gint                champlain_view_get_max_zoom_level   (ChamplainView *view);

Gets the view's maximal allowed zoom level.

`view` : | The view
Returns : | the view's maximal allowed zoom level.

Since 0.4

### champlain_view_set_map_source ()

    void                champlain_view_set_map_source       (ChamplainView *view,
                                                             ChamplainMapSource *map_source);

Changes the currently used map source. g_object_unref will be called on the previous one.

`view` : | a ChamplainView
`map_source` : | a ChamplainMapSource

Since 0.4

### champlain_view_get_map_source ()

    ChamplainMapSource * champlain_view_get_map_source      (ChamplainView *view);

Gets the view's current map source.

`view` : | The view
Returns : | the view's current map source. If you need to keep a reference to the map source then you have to call g_object_ref. [transfer none]

Since 0.4

### champlain_view_set_size ()

    void                champlain_view_set_size             (ChamplainView *view,
                                                             guint width,
                                                             guint height);

Sets the size of the view. This function is deprecated and should not be used in new code Use clutter_actor_set_size instead.

`view` : | a ChamplainView
`width` : | the width in pixels
`height` : | the height in pixels

Since 0.1

### champlain_view_set_decel_rate ()

    void                champlain_view_set_decel_rate       (ChamplainView *view,
                                                             gdouble rate);

The deceleration rate for the kinetic mode.

`view` : | a ChamplainView
`rate` : | a gdouble between 1.001 and 2.0

Since 0.4

### champlain_view_get_decel_rate ()

    gdouble             champlain_view_get_decel_rate       (ChamplainView *view);

Gets the view's deceleration rate.

`view` : | The view
Returns : | the view's deceleration rate.

Since 0.4

### champlain_view_set_scroll_mode ()

    void                champlain_view_set_scroll_mode      (ChamplainView *view,
                                                             ChamplainScrollMode mode);

Determines the way the view reacts to scroll events.

`view` : | a ChamplainView
`mode` : | a ChamplainScrollMode value

Since 0.4

### champlain_view_get_scroll_mode ()

    ChamplainScrollMode  champlain_view_get_scroll_mode     (ChamplainView *view);

Gets the view's scroll mode behaviour.

`view` : | The view
Returns : | the view's scroll mode behaviour.

Since 0.4

### champlain_view_set_keep_center_on_resize ()

    void                champlain_view_set_keep_center_on_resize
                                                            (ChamplainView *view,
                                                             gboolean value);

Keep the current centered position when resizing the view.

`view` : | a ChamplainView
`value` : | a gboolean

Since 0.4

### champlain_view_get_keep_center_on_resize ()

    gboolean            champlain_view_get_keep_center_on_resize
                                                            (ChamplainView *view);

Checks whether to keep the center on resize

`view` : | The view
Returns : | TRUE if the view keeps the center on resize, FALSE otherwise.

Since 0.4

### champlain_view_set_show_license ()

    void                champlain_view_set_show_license     (ChamplainView *view,
                                                             gboolean value);

Show the license on the map view. The license information should always be available in a way or another in your application. You can have it in About, or on the map.

`view` : | a ChamplainView
`value` : | a gboolean

Since 0.4

### champlain_view_get_show_license ()

    gboolean            champlain_view_get_show_license     (ChamplainView *view);

Checks whether the view displays the license.

`view` : | The view
Returns : | TRUE if the view displays the license, FALSE otherwise.

Since 0.4

### champlain_view_set_zoom_level ()

    void                champlain_view_set_zoom_level       (ChamplainView *view,
                                                             gint zoom_level);

Changes the current zoom level

`view` : | a ChamplainView
`zoom_level` : | a gint

Since 0.4

### champlain_view_get_zoom_level ()

    gint                champlain_view_get_zoom_level       (ChamplainView *view);

Gets the view's current zoom level.

`view` : | The view
Returns : | the view's current zoom level.

Since 0.4

### champlain_view_set_zoom_on_double_click ()

    void                champlain_view_set_zoom_on_double_click
                                                            (ChamplainView *view,
                                                             gboolean value);

Should the view zoom in and recenter when the user double click on the map.

`view` : | a ChamplainView
`value` : | a gboolean

Since 0.4

### champlain_view_get_zoom_on_double_click ()

    gboolean            champlain_view_get_zoom_on_double_click
                                                            (ChamplainView *view);

Checks whether the view zooms on double click.

`view` : | The view
Returns : | TRUE if the view zooms on double click, FALSE otherwise.

Since 0.4

### champlain_view_set_license_text ()

    void                champlain_view_set_license_text     (ChamplainView *view,
                                                             const gchar *text);

Show the additional license text on the map view. The text will preceed the map's licence when displayed. Use "\n" to separate the lines.

`view` : | a ChamplainView
`text` : | a license

Since 0.4.3

### champlain_view_get_license_text ()

    const gchar *       champlain_view_get_license_text     (ChamplainView *view);

Gets the additional license text.

`view` : | The view
Returns : | the additional license text

Since 0.4.3

### champlain_view_set_max_scale_width ()

    void                champlain_view_set_max_scale_width  (ChamplainView *view,
                                                             guint value);

Sets the maximum width of the scale on the screen in pixels

`view` : | a ChamplainView
`value` : | a guint in pixels

Since 0.4.3

### champlain_view_get_max_scale_width ()

    guint               champlain_view_get_max_scale_width  (ChamplainView *view);

Gets the maximal scale width.

`view` : | The view
Returns : | The max scale width in pixels.

Since 0.4.3

### champlain_view_set_scale_unit ()

    void                champlain_view_set_scale_unit       (ChamplainView *view,
                                                             ChamplainUnit unit);

Sets the scales unit.

`view` : | a ChamplainView
`unit` : | a ChamplainUnit

Since 0.4.3

### champlain_view_get_scale_unit ()

    ChamplainUnit       champlain_view_get_scale_unit       (ChamplainView *view);

Gets the unit used by the scale.

`view` : | The view
Returns : | The unit used by the scale

Since 0.4.3

### champlain_view_set_show_scale ()

    void                champlain_view_set_show_scale       (ChamplainView *view,
                                                             gboolean value);

Show the scale on the map view.

`view` : | a ChamplainView
`value` : | a gboolean

Since 0.4.3

### champlain_view_get_show_scale ()

    gboolean            champlain_view_get_show_scale       (ChamplainView *view);

Checks whether the view displays the scale.

`view` : | The view
Returns : | TRUE if the view displays the scale, FALSE otherwise.

Since 0.4.3

### champlain_view_add_layer ()

    void                champlain_view_add_layer            (ChamplainView *view,
                                                             ChamplainLayer *layer);

Adds a new layer to the view

`view` : | a ChamplainView
`layer` : | a ChamplainLayer

Since 0.2

### champlain_view_remove_layer ()

    void                champlain_view_remove_layer         (ChamplainView *view,
                                                             ChamplainLayer *layer);

Removes the layer from the view

`view` : | a ChamplainView
`layer` : | a ChamplainLayer

Since 0.4.1

### champlain_view_get_coords_from_event ()

    gboolean            champlain_view_get_coords_from_event
                                                            (ChamplainView *view,
                                                             ClutterEvent *event,
                                                             gdouble *lat,
                                                             gdouble *lon);

Gets coordinates from button-press-event and button-release-event signals.

`view` : | a ChamplainView
`event` : | a ClutterEvent
`lat` : | a variable where to put the latitude of the event. [out]
`lon` : | a variable where to put the longitude of the event. [out]
Returns : | the latitude, longitude coordinates for the given ClutterEvent.

Since 0.2.8

### champlain_view_get_coords_at ()

    gboolean            champlain_view_get_coords_at        (ChamplainView *view,
                                                             guint x,
                                                             guint y,
                                                             gdouble *lat,
                                                             gdouble *lon);

Gets latitude and longitude for the given x, y position in the view. Use if you get coordinates from GtkEvents for example.

`view` : | a ChamplainView
`x` : | the x position in the view
`y` : | the y position in the view
`lat` : | a variable where to put the latitude of the event. [out]
`lon` : | a variable where to put the longitude of the event. [out]
Returns : | TRUE when successful.

Since 0.4

### champlain_view_add_polygon ()

    void                champlain_view_add_polygon          (ChamplainView *view,
                                                             ChamplainPolygon *polygon);

Adds a ChamplainPolygon to the ChamplainView

`view` : | a ChamplainView
`polygon` : | a ChamplainPolygon

Since 0.4

### champlain_view_remove_polygon ()

    void                champlain_view_remove_polygon       (ChamplainView *view,
                                                             ChamplainPolygon *polygon);

Removes a ChamplainPolygon from ChamplainView

`view` : | a ChamplainView
`polygon` : | a ChamplainPolygon

Since 0.4

### champlain_view_reload_tiles ()

    void                champlain_view_reload_tiles         (ChamplainView *view);

Reloads all visible tiles.

`view` : | a ChamplainView

Since 0.8

## Property Details

### The `"decel-rate"` property

      "decel-rate"               gdouble               : Read / Write

The deceleration rate for the kinetic mode. The default value is 1.1.

Allowed values: [1.0001,2]

Default value: 1.1

Since 0.2

### The `"keep-center-on-resize"` property

      "keep-center-on-resize"    gboolean              : Read / Write

Keep the current centered position when resizing the view.

Default value: TRUE

Since 0.2.7

### The `"latitude"` property

      "latitude"                 gdouble               : Read / Write

The latitude coordonate of the map

Allowed values: [-90,90]

Default value: 0

Since 0.1

### The `"license-text"` property

      "license-text"             gchar*                : Read / Write

Sets additional text to be displayed in the license area. The map's license will be added below it. Your text can have multiple line, just use "\n" in between.

Default value: ""

Since 0.4.3

### The `"longitude"` property

      "longitude"                gdouble               : Read / Write

The longitude coordonate of the map

Allowed values: [-180,180]

Default value: 0

Since 0.1

### The `"map-source"` property

      "map-source"               ChamplainMapSource*   : Read / Write

The ChamplainMapSource being displayed

Since 0.2

### The `"max-scale-width"` property

      "max-scale-width"          guint                 : Read / Write

The size of the map scale on screen in pixels.

Allowed values: [1,2000]

Default value: 100

Since 0.4.3

### The `"max-zoom-level"` property

      "max-zoom-level"           gint                  : Read / Write

The highest allowed level of zoom of the content.

Allowed values: [0,20]

Default value: 20

Since 0.4

### The `"min-zoom-level"` property

      "min-zoom-level"           gint                  : Read / Write

The lowest allowed level of zoom of the content.

Allowed values: [0,20]

Default value: 0

Since 0.4

### The `"scale-unit"` property

      "scale-unit"               ChamplainUnit         : Read / Write

The scale's units.

Default value: CHAMPLAIN_UNIT_KM

Since 0.4.3

### The `"scroll-mode"` property

      "scroll-mode"              ChamplainScrollMode   : Read / Write

Determines the way the view reacts to scroll events.

Default value: CHAMPLAIN_SCROLL_MODE_KINETIC

Since 0.4

### The `"show-license"` property

      "show-license"             gboolean              : Read / Write

Show the license on the map view. The license information should always be available in a way or another in your application. You can have it in About, or on the map.

Default value: TRUE

Since 0.2.8

### The `"show-scale"` property

      "show-scale"               gboolean              : Read / Write

Display the map scale.

Default value: FALSE

Since 0.4.3

### The `"state"` property

      "state"                    ChamplainState        : Read

The view's global state. Useful to inform using if the view is busy loading tiles or not.

Default value: CHAMPLAIN_STATE_NONE

Since 0.4

### The `"zoom-level"` property

      "zoom-level"               gint                  : Read / Write

The level of zoom of the content.

Allowed values: [0,20]

Default value: 3

Since 0.1

### The `"zoom-on-double-click"` property

      "zoom-on-double-click"     gboolean              : Read / Write

Should the view zoom in and recenter when the user double click on the map.

Default value: TRUE

Since 0.4

## Signal Details

### The `"animation-completed"` signal

    void                user_function                      (ChamplainView *arg0,
                                                            gpointer       user_data)      : Has Details

The "animation-completed" signal is emitted when any animation in the view ends. This is a detailed signal. For example, if you want to be signaled only for go-to animation, you should connect to "animation-completed::go-to".

`user_data` : | user data set when the signal handler was connected.

Since 0.4