ChamplainView

ChamplainView — A ClutterActor to display maps

Functions

ClutterActor * champlain_view_new ()
void champlain_view_center_on ()
void champlain_view_go_to ()
void champlain_view_stop_go_to ()
void champlain_view_zoom_in ()
void champlain_view_zoom_out ()
void champlain_view_set_zoom_level ()
void champlain_view_set_min_zoom_level ()
void champlain_view_set_max_zoom_level ()
void champlain_view_set_world ()
ChamplainBoundingBox * champlain_view_get_world ()
void champlain_view_ensure_visible ()
void champlain_view_ensure_layers_visible ()
void champlain_view_set_map_source ()
void champlain_view_add_overlay_source ()
void champlain_view_remove_overlay_source ()
GList * champlain_view_get_overlay_sources ()
void champlain_view_set_deceleration ()
void champlain_view_set_kinetic_mode ()
void champlain_view_set_keep_center_on_resize ()
void champlain_view_set_zoom_on_double_click ()
void champlain_view_set_animate_zoom ()
void champlain_view_set_background_pattern ()
void champlain_view_set_horizontal_wrap ()
void champlain_view_add_layer ()
void champlain_view_remove_layer ()
guint champlain_view_get_zoom_level ()
guint champlain_view_get_min_zoom_level ()
guint champlain_view_get_max_zoom_level ()
ChamplainMapSource * champlain_view_get_map_source ()
gdouble champlain_view_get_deceleration ()
gboolean champlain_view_get_kinetic_mode ()
gboolean champlain_view_get_keep_center_on_resize ()
gboolean champlain_view_get_zoom_on_double_click ()
gboolean champlain_view_get_animate_zoom ()
ClutterContent * champlain_view_get_background_pattern ()
gboolean champlain_view_get_horizontal_wrap ()
void champlain_view_reload_tiles ()
cairo_surface_t * champlain_view_to_surface ()
gdouble champlain_view_x_to_longitude ()
gdouble champlain_view_y_to_latitude ()
gdouble champlain_view_longitude_to_x ()
gdouble champlain_view_latitude_to_y ()
void champlain_view_get_viewport_origin ()
void champlain_view_bin_layout_add ()
ChamplainLicense * champlain_view_get_license_actor ()
gdouble champlain_view_get_center_latitude ()
gdouble champlain_view_get_center_longitude ()
ChamplainBoundingBox * champlain_view_get_bounding_box ()
ChamplainBoundingBox * champlain_view_get_bounding_box_for_zoom_level ()
ChamplainState champlain_view_get_state ()
void champlain_view_get_viewport_anchor ()

Properties

Signals

void animation-completed Has Details
void layer-relocated Run Last

Types and Values

struct ChamplainView

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── ClutterActor
            ╰── ChamplainView

Implemented Interfaces

ChamplainView implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

Description

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

  • Push: the normal behavior where the maps don'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 and released on the view .

Functions

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.

Parameters

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!

Parameters

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.

Parameters

view

a ChamplainView

 

Since 0.4


champlain_view_zoom_in ()

void
champlain_view_zoom_in (ChamplainView *view);

Zoom in the map by one level.

Parameters

view

a ChamplainView

 

Since 0.1


champlain_view_zoom_out ()

void
champlain_view_zoom_out (ChamplainView *view);

Zoom out the map by one level.

Parameters

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 level of zoom

Parameters

view

a ChamplainView

 

zoom_level

the level of zoom, a guint between 1 and 20

 

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 level of zoom

Parameters

view

a ChamplainView

 

zoom_level

the level of zoom

 

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 level of zoom

Parameters

view

a ChamplainView

 

zoom_level

the level of zoom

 

Since 0.4


champlain_view_set_world ()

void
champlain_view_set_world (ChamplainView *view,
                          ChamplainBoundingBox *bbox);

Set a bounding box to limit the world to. No tiles will be loaded outside of this bounding box. It will not be possible to scroll outside of this bounding box.

Parameters

view

a ChamplainView

 

bbox

the ChamplainBoundingBox of the world.

[transfer none]

Since 0.12.11


champlain_view_get_world ()

ChamplainBoundingBox *
champlain_view_get_world (ChamplainView *view);

Get the bounding box that represents the extent of the world.

Parameters

view

a ChamplainView

 

Returns

a ChamplainBoundingBox that represents the current world.

[transfer none]

Since 0.12.11


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 given area is visible

Parameters

view

a ChamplainView

 

bbox

bounding box of the area that should be visible

 

animate

TRUE to perform animation, FALSE otherwise

 

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.

Parameters

view

a ChamplainView

 

animate

TRUE to perform animation, FALSE otherwise

 

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.

As a side effect, changing the primary map source will also clear all secondary map sources.

Parameters

view

a ChamplainView

 

map_source

a ChamplainMapSource

 

Since 0.4


champlain_view_add_overlay_source ()

void
champlain_view_add_overlay_source (ChamplainView *view,
                                   ChamplainMapSource *map_source,
                                   guint8 opacity);

Adds a new overlay map source to render tiles with the supplied opacity on top of the ordinary map source. Multiple overlay sources can be added.

Parameters

view

a ChamplainView

 

map_source

a ChamplainMapSource

 

opacity

opacity to use

 

Since 0.12.5


champlain_view_remove_overlay_source ()

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

Removes an overlay source from ChamplainView.

Parameters

view

a ChamplainView

 

map_source

a ChamplainMapSource

 

Since 0.12.5


champlain_view_get_overlay_sources ()

GList *
champlain_view_get_overlay_sources (ChamplainView *view);

Gets a list of overlay sources.

Parameters

view

a ChamplainView

 

Returns

the list.

[transfer container][element-type ChamplainMapSource]

Since 0.12.5


champlain_view_set_deceleration ()

void
champlain_view_set_deceleration (ChamplainView *view,
                                 gdouble rate);

The deceleration rate for the kinetic mode.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

view

a ChamplainView

 

value

a gboolean

 

Since 0.12


champlain_view_set_background_pattern ()

void
champlain_view_set_background_pattern (ChamplainView *view,
                                       ClutterContent *background);

Sets the background texture displayed behind the map. Setting the background pattern affects performence slightly - use reasonably large patterns for better performance.

Parameters

view

a ChamplainView

 

background

The background texture

 

Since 0.12.4


champlain_view_set_horizontal_wrap ()

void
champlain_view_set_horizontal_wrap (ChamplainView *view,
                                    gboolean wrap);

Sets the value of the “horizontal-wrap” property.

Parameters

view

a ChamplainView

 

wrap

TRUE to enable horizontal wrapping

 

champlain_view_add_layer ()

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

Adds a new layer to the view

Parameters

view

a ChamplainView

 

layer

a ChamplainLayer

 

Since 0.2


champlain_view_remove_layer ()

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

Removes the given layer from the view

Parameters

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.

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

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 maximum allowed zoom level.

Parameters

view

a ChamplainView

 

Returns

the view's maximum 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.

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

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

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

Returns

TRUE if the view animates zooms, FALSE otherwise.

Since 0.12


champlain_view_get_background_pattern ()

ClutterContent *
champlain_view_get_background_pattern (ChamplainView *view);

Gets the current background texture displayed behind the map.

Parameters

view

a ChamplainView

 

Returns

The texture.

[transfer none]

Since 0.12.4


champlain_view_get_horizontal_wrap ()

gboolean
champlain_view_get_horizontal_wrap (ChamplainView *view);

Returns the value of the “horizontal-wrap” property.

Parameters

view

a ChamplainView

 

Returns

TRUE if “horizontal-wrap” is set.

[transfer none]


champlain_view_reload_tiles ()

void
champlain_view_reload_tiles (ChamplainView *view);

Reloads all visible tiles.

Parameters

view

a ChamplainView

 

Since 0.8


champlain_view_to_surface ()

cairo_surface_t *
champlain_view_to_surface (ChamplainView *view,
                           gboolean include_layers);

Will generate a cairo_surface_t that represents the current view of the map. Without any markers or layers. If the current ChamplainRenderer used does not support this, this function will return NULL.

If include_layers is set to TRUE all layers that implement ChamplainExportable will be included in the surface.

The ChamplainView also need to be in CHAMPLAIN_STATE_DONE state.

Parameters

view

a ChamplainView

 

include_layers

Set to TRUE if you want to include layers

 

Returns

a cairo_surface_t or NULL on failure. Free with cairo_surface_destroy() when done.

[transfer full]


champlain_view_x_to_longitude ()

gdouble
champlain_view_x_to_longitude (ChamplainView *view,
                               gdouble x);

Converts the view's x coordinate to longitude.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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);

champlain_view_bin_layout_add has been deprecated since version 0.12.4 and should not be used in newly-written code.

Use ClutterActorAlign and the ClutterActor API instead.

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

Parameters

view

a ChamplainView

 

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).

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

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.

Parameters

view

a ChamplainView

 

Returns

the longitude.

Since 0.10


champlain_view_get_bounding_box ()

ChamplainBoundingBox *
champlain_view_get_bounding_box (ChamplainView *view);

Gets the bounding box for view view at current zoom-level.

Parameters

view

a ChamplainView

 

Returns

the bounding box.

[transfer full]

Since 0.12.4


champlain_view_get_bounding_box_for_zoom_level ()

ChamplainBoundingBox *
champlain_view_get_bounding_box_for_zoom_level
                               (ChamplainView *view,
                                guint zoom_level);

Gets the bounding box for view view at zoom_level .

Parameters

view

a ChamplainView

 

zoom_level

the level of zoom, a guint between 1 and 20

 

Returns

the bounding box for the view at zoom_level .

[transfer full]

Since 0.12.6


champlain_view_get_state ()

ChamplainState
champlain_view_get_state (ChamplainView *view);

Gets the view's state.

Parameters

view

a ChamplainView

 

Returns

the state.

Since 0.10


champlain_view_get_viewport_anchor ()

void
champlain_view_get_viewport_anchor (ChamplainView *view,
                                    gint *anchor_x,
                                    gint *anchor_y);

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

Parameters

view

a ChamplainView

 

anchor_x

the x coordinate of the viewport anchor.

[out]

anchor_y

the y coordinate of the viewport anchor.

[out]

Since 0.12.14

Types and Values

struct ChamplainView

struct ChamplainView;

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

Since 0.1

Property Details

The “animate-zoom” property

  “animate-zoom”             gboolean

Animate zoom change when zooming in/out.

Flags: Read / Write

Default value: TRUE

Since 0.12


The “background-pattern” property

  “background-pattern”       ClutterActor *

The pattern displayed in the background of the map.

Flags: Read / Write

Since 0.12.4


The “deceleration” property

  “deceleration”             gdouble

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

Flags: Read / Write

Allowed values: [1.0001,2]

Default value: 1.1

Since 0.10


The “goto-animation-duration” property

  “goto-animation-duration”  guint

The duration of an animation when going to a location. A value of 0 means that the duration is calculated automatically for you.

Please note that animation of champlain_view_ensure_visible also involves a 'goto' animation.

Flags: Read / Write

Allowed values: <= G_MAXINT

Default value: 0


The “goto-animation-mode” property

  “goto-animation-mode”      ClutterAnimationMode

The mode of animation when going to a location.

Please note that animation of champlain_view_ensure_visible also involves a 'goto' animation.

Flags: Read / Write

Default value: CLUTTER_EASE_IN_OUT_CIRC


The “horizontal-wrap” property

  “horizontal-wrap”          gboolean

Determines whether the view should wrap horizontally.

Flags: Read / Write

Default value: FALSE


The “keep-center-on-resize” property

  “keep-center-on-resize”    gboolean

Keep the current centered position when resizing the view.

Flags: Read / Write

Default value: TRUE

Since 0.2.7


The “kinetic-mode” property

  “kinetic-mode”             gboolean

Determines whether the view should use kinetic mode.

Flags: Read / Write

Default value: FALSE

Since 0.10


The “latitude” property

  “latitude”                 gdouble

The latitude coordonate of the map

Flags: Read / Write

Allowed values: [-90,90]

Default value: 0

Since 0.1


The “longitude” property

  “longitude”                gdouble

The longitude coordonate of the map

Flags: Read / Write

Allowed values: [-180,180]

Default value: 0

Since 0.1


The “map-source” property

  “map-source”               ChamplainMapSource *

The ChamplainMapSource being displayed

Flags: Read / Write

Since 0.2


The “max-zoom-level” property

  “max-zoom-level”           guint

The highest allowed level of zoom of the content.

Flags: Read / Write

Allowed values: <= 20

Default value: 20

Since 0.4


The “min-zoom-level” property

  “min-zoom-level”           guint

The lowest allowed level of zoom of the content.

Flags: Read / Write

Allowed values: <= 20

Default value: 0

Since 0.4


The “state” property

  “state”                    ChamplainState

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

Flags: Read

Default value: CHAMPLAIN_STATE_NONE

Since 0.4


The “world” property

  “world”                    ChamplainBoundingBox *

Set a bounding box to limit the world to. No tiles will be loaded outside of this bounding box. It will not be possible to scroll outside of this bounding box.

Default world is the actual world.

Flags: Read / Write

Since 0.12.11


The “zoom-level” property

  “zoom-level”               guint

The level of zoom of the content.

Flags: Read / Write

Allowed values: <= 20

Default value: 3

Since 0.1


The “zoom-on-double-click” property

  “zoom-on-double-click”     gboolean

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

Flags: Read / Write

Default value: TRUE

Since 0.4

Signal Details

The “animation-completed” signal

void
user_function (ChamplainView *arg0,
               gpointer       user_data)

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". And for zoom, connect to "animation-completed::zoom".

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

Since 0.4


The “layer-relocated” signal

void
user_function (ChamplainView *arg0,
               gpointer       user_data)

Indicates that the layers have 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.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.10