ChamplainView

ChamplainView — A ClutterActor to display maps

Synopsis

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_set_zoom_level       (ChamplainView *view,
                                                         guint zoom_level);
void                champlain_view_set_min_zoom_level   (ChamplainView *view,
                                                         guint zoom_level);
void                champlain_view_set_max_zoom_level   (ChamplainView *view,
                                                         guint zoom_level);
void                champlain_view_ensure_visible       (ChamplainView *view,
                                                         ChamplainBoundingBox *bbox,
                                                         gboolean animate);
void                champlain_view_ensure_layers_visible
                                                        (ChamplainView *view,
                                                         gboolean animate);
void                champlain_view_set_map_source       (ChamplainView *view,
                                                         ChamplainMapSource *map_source);
void                champlain_view_set_deceleration     (ChamplainView *view,
                                                         gdouble rate);
void                champlain_view_set_kinetic_mode     (ChamplainView *view,
                                                         gboolean kinetic);
void                champlain_view_set_keep_center_on_resize
                                                        (ChamplainView *view,
                                                         gboolean value);
void                champlain_view_set_zoom_on_double_click
                                                        (ChamplainView *view,
                                                         gboolean value);
void                champlain_view_set_animate_zoom     (ChamplainView *view,
                                                         gboolean value);
void                champlain_view_add_layer            (ChamplainView *view,
                                                         ChamplainLayer *layer);
void                champlain_view_remove_layer         (ChamplainView *view,
                                                         ChamplainLayer *layer);
guint               champlain_view_get_zoom_level       (ChamplainView *view);
guint               champlain_view_get_min_zoom_level   (ChamplainView *view);
guint               champlain_view_get_max_zoom_level   (ChamplainView *view);
ChamplainMapSource * champlain_view_get_map_source      (ChamplainView *view);
gdouble             champlain_view_get_deceleration     (ChamplainView *view);
gboolean            champlain_view_get_kinetic_mode     (ChamplainView *view);
gboolean            champlain_view_get_keep_center_on_resize
                                                        (ChamplainView *view);
gboolean            champlain_view_get_zoom_on_double_click
                                                        (ChamplainView *view);
gboolean            champlain_view_get_animate_zoom     (ChamplainView *view);
void                champlain_view_reload_tiles         (ChamplainView *view);
gdouble             champlain_view_x_to_longitude       (ChamplainView *view,
                                                         gdouble x);
gdouble             champlain_view_y_to_latitude        (ChamplainView *view,
                                                         gdouble y);
gdouble             champlain_view_longitude_to_x       (ChamplainView *view,
                                                         gdouble longitude);
gdouble             champlain_view_latitude_to_y        (ChamplainView *view,
                                                         gdouble latitude);
void                champlain_view_get_viewport_origin  (ChamplainView *view,
                                                         gint *x,
                                                         gint *y);
void                champlain_view_bin_layout_add       (ChamplainView *view,
                                                         ClutterActor *child,
                                                         ClutterBinAlignment x_align,
                                                         ClutterBinAlignment y_align);
ChamplainLicense *  champlain_view_get_license_actor    (ChamplainView *view);
gdouble             champlain_view_get_center_latitude  (ChamplainView *view);
gdouble             champlain_view_get_center_longitude (ChamplainView *view);
ChamplainState      champlain_view_get_state            (ChamplainView *view);

Object Hierarchy

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

Implemented Interfaces

ChamplainView implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

Properties

  "animate-zoom"             gboolean              : Read / Write
  "deceleration"             gdouble               : Read / Write
  "keep-center-on-resize"    gboolean              : Read / Write
  "kinetic-mode"             gboolean              : Read / Write
  "latitude"                 gdouble               : Read / Write
  "longitude"                gdouble               : Read / Write
  "map-source"               ChamplainMapSource*   : Read / Write
  "max-zoom-level"           guint                 : Read / Write
  "min-zoom-level"           guint                 : Read / Write
  "state"                    ChamplainState        : Read
  "zoom-level"               guint                 : Read / Write
  "zoom-on-double-click"     gboolean              : Read / Write

Signals

  "animation-completed"                            : Has Details
  "layer-relocated"                                : Run Last

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.

Details

struct ChamplainView

struct ChamplainView;

The ChamplainView structure contains only private data and should be accessed using the provided API

Since 0.1


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_set_zoom_level ()

void                champlain_view_set_zoom_level       (ChamplainView *view,
                                                         guint zoom_level);

Changes the current zoom level

view :

a ChamplainView

zoom_level :

a guint

Since 0.4


champlain_view_set_min_zoom_level ()

void                champlain_view_set_min_zoom_level   (ChamplainView *view,
                                                         guint zoom_level);

Changes the lowest allowed zoom level

view :

a ChamplainView

zoom_level :

a guint

Since 0.4


champlain_view_set_max_zoom_level ()

void                champlain_view_set_max_zoom_level   (ChamplainView *view,
                                                         guint zoom_level);

Changes the highest allowed zoom level

view :

a ChamplainView

zoom_level :

a guint

Since 0.4


champlain_view_ensure_visible ()

void                champlain_view_ensure_visible       (ChamplainView *view,
                                                         ChamplainBoundingBox *bbox,
                                                         gboolean animate);

Changes the map's zoom level and center to make sure the two given area is visible

view :

a ChamplainView

bbox :

bounding box of the area that should be visible

animate :

perform animation

Since 0.10


champlain_view_ensure_layers_visible ()

void                champlain_view_ensure_layers_visible
                                                        (ChamplainView *view,
                                                         gboolean animate);

Changes the map's zoom level and center to make sure that the bounding boxes of all inserted layers are visible.

view :

a ChamplainView

animate :

perform animation

Since 0.10


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_set_deceleration ()

void                champlain_view_set_deceleration     (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_set_kinetic_mode ()

void                champlain_view_set_kinetic_mode     (ChamplainView *view,
                                                         gboolean kinetic);

Determines the way the view reacts to scroll events.

view :

a ChamplainView

kinetic :

TRUE for kinetic mode, FALSE for push mode

Since 0.10


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_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_set_animate_zoom ()

void                champlain_view_set_animate_zoom     (ChamplainView *view,
                                                         gboolean value);

Should the view animate zoom level changes.

view :

a ChamplainView

value :

a gboolean

Since 0.12


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_zoom_level ()

guint               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_get_min_zoom_level ()

guint               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_get_max_zoom_level ()

guint               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_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_get_deceleration ()

gdouble             champlain_view_get_deceleration     (ChamplainView *view);

Gets the view's deceleration rate.

view :

The view

Returns :

the view's deceleration rate.

Since 0.4


champlain_view_get_kinetic_mode ()

gboolean            champlain_view_get_kinetic_mode     (ChamplainView *view);

Gets the view's scroll mode behaviour.

view :

The view

Returns :

TRUE for kinetic mode, FALSE for push mode.

Since 0.10


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_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_get_animate_zoom ()

gboolean            champlain_view_get_animate_zoom     (ChamplainView *view);

Checks whether the view animates zoom level changes.

view :

The view

Returns :

TRUE if the view animates zooms, FALSE otherwise.

Since 0.12


champlain_view_reload_tiles ()

void                champlain_view_reload_tiles         (ChamplainView *view);

Reloads all visible tiles.

view :

a ChamplainView

Since 0.8


champlain_view_x_to_longitude ()

gdouble             champlain_view_x_to_longitude       (ChamplainView *view,
                                                         gdouble x);

Converts the view's x coordinate to longitude.

view :

a ChamplainView

x :

x coordinate of the view

Returns :

the longitude

Since 0.10


champlain_view_y_to_latitude ()

gdouble             champlain_view_y_to_latitude        (ChamplainView *view,
                                                         gdouble y);

Converts the view's y coordinate to latitude.

view :

a ChamplainView

y :

y coordinate of the view

Returns :

the latitude

Since 0.10


champlain_view_longitude_to_x ()

gdouble             champlain_view_longitude_to_x       (ChamplainView *view,
                                                         gdouble longitude);

Converts the longitude to view's x coordinate.

view :

a ChamplainView

longitude :

the longitude

Returns :

the x coordinate

Since 0.10


champlain_view_latitude_to_y ()

gdouble             champlain_view_latitude_to_y        (ChamplainView *view,
                                                         gdouble latitude);

Converts the latitude to view's y coordinate.

view :

a ChamplainView

latitude :

the latitude

Returns :

the y coordinate

Since 0.10


champlain_view_get_viewport_origin ()

void                champlain_view_get_viewport_origin  (ChamplainView *view,
                                                         gint *x,
                                                         gint *y);

Gets the x and y coordinate of the viewport in respect to the layer origin.

view :

a ChamplainView

x :

the x coordinate of the viewport. [out]

y :

the y coordinate of the viewport. [out]

Since 0.10


champlain_view_bin_layout_add ()

void                champlain_view_bin_layout_add       (ChamplainView *view,
                                                         ClutterActor *child,
                                                         ClutterBinAlignment x_align,
                                                         ClutterBinAlignment y_align);

This function iserts a custom actor to the undrelying ClutterBinLayout manager. The inserted actors appear on top of the map. See clutter_bin_layout_add() for reference.

view :

The view

child :

The child to be inserted

x_align :

x alignment

y_align :

y alignment

Since 0.10


champlain_view_get_license_actor ()

ChamplainLicense *  champlain_view_get_license_actor    (ChamplainView *view);

Returns the ChamplainLicense actor which is inserted by default into the layout manager. It can be manipulated using standard ClutterActor methods (hidden and so on).

view :

The view

Returns :

the license actor. [transfer none]

Since 0.10


champlain_view_get_center_latitude ()

gdouble             champlain_view_get_center_latitude  (ChamplainView *view);

Gets the latitude of the view's center.

view :

The view

Returns :

the latitude.

Since 0.10


champlain_view_get_center_longitude ()

gdouble             champlain_view_get_center_longitude (ChamplainView *view);

Gets the longitude of the view's center.

view :

The view

Returns :

the latitude.

Since 0.10


champlain_view_get_state ()

ChamplainState      champlain_view_get_state            (ChamplainView *view);

Gets the view's state.

view :

The view

Returns :

the state.

Since 0.10

Property Details

The "animate-zoom" property

  "animate-zoom"             gboolean              : Read / Write

Animate zoom change when zooming in/out.

Default value: TRUE

Since 0.12


The "deceleration" property

  "deceleration"             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.10


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 "kinetic-mode" property

  "kinetic-mode"             gboolean              : Read / Write

Determines whether the view should use kinetic mode.

Default value: FALSE

Since 0.10


The "latitude" property

  "latitude"                 gdouble               : Read / Write

The latitude coordonate of the map

Allowed values: [-90,90]

Default value: 0

Since 0.1


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-zoom-level" property

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

The highest allowed level of zoom of the content.

Allowed values: <= 20

Default value: 20

Since 0.4


The "min-zoom-level" property

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

The lowest allowed level of zoom of the content.

Allowed values: <= 20

Default value: 0

Since 0.4


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"               guint                 : Read / Write

The level of zoom of the content.

Allowed values: <= 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


The "layer-relocated" signal

void                user_function                      (ChamplainView *arg0,
                                                        gpointer       user_data)      : Run Last

Indicates that the layers hav been "relocated". In practice this means that every layer should connect to this signal and redraw itself when the signal is emitted. Layer relocation happens when zooming in/out and when panning for more than MAX_INT pixels.

user_data :

user data set when the signal handler was connected.

Since 0.10