Champlain.View¶

Subclasses:: None

Methods¶

Inherited:: Clutter.Actor (238), GObject.Object (37), Clutter.Animatable (5), Clutter.Container (17), Clutter.Scriptable (4)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add_layer` (layer)
	`add_overlay_source` (map_source, opacity)
	`bin_layout_add` (child, x_align, y_align)
	`center_on` (latitude, longitude)
	`ensure_layers_visible` (animate)
	`ensure_visible` (bbox, animate)
	`get_animate_zoom` ()
	`get_background_pattern` ()
	`get_bounding_box` ()
	`get_bounding_box_for_zoom_level` (zoom_level)
	`get_center_latitude` ()
	`get_center_longitude` ()
	`get_deceleration` ()
	`get_horizontal_wrap` ()
	`get_keep_center_on_resize` ()
	`get_kinetic_mode` ()
	`get_license_actor` ()
	`get_map_source` ()
	`get_max_zoom_level` ()
	`get_min_zoom_level` ()
	`get_overlay_sources` ()
	`get_state` ()
	`get_viewport_anchor` ()
	`get_viewport_origin` ()
	`get_world` ()
	`get_zoom_level` ()
	`get_zoom_on_double_click` ()
	`go_to` (latitude, longitude)
	`latitude_to_y` (latitude)
	`longitude_to_x` (longitude)
	`reload_tiles` ()
	`remove_layer` (layer)
	`remove_overlay_source` (map_source)
	`set_animate_zoom` (value)
	`set_background_pattern` (background)
	`set_deceleration` (rate)
	`set_horizontal_wrap` (wrap)
	`set_keep_center_on_resize` (value)
	`set_kinetic_mode` (kinetic)
	`set_map_source` (map_source)
	`set_max_zoom_level` (zoom_level)
	`set_min_zoom_level` (zoom_level)
	`set_world` (bbox)
	`set_zoom_level` (zoom_level)
	`set_zoom_on_double_click` (value)
	`stop_go_to` ()
	`to_surface` (include_layers)
	`x_to_longitude` (x)
	`y_to_latitude` (y)
	`zoom_in` ()
	`zoom_out` ()

Virtual Methods¶

Inherited:: Clutter.Actor (35), GObject.Object (7), Clutter.Animatable (5), Clutter.Container (13), Clutter.Scriptable (4)

Properties¶

Inherited:: Clutter.Actor (82)

Name	Type	Flags	Short Description
`animate-zoom`	`bool`	r/w	Animate zoom change when zooming in/out
`background-pattern`	`Clutter.Actor`	r/w	The tile’s background pattern
`deceleration`	`float`	r/w	Rate at which the view will decelerate in kinetic mode.
`goto-animation-duration`	`int`	r/w	The duration of an animation when going to a location
`goto-animation-mode`	`Clutter.AnimationMode`	r/w	The mode of animation when going to a location
`horizontal-wrap`	`bool`	r/w	Determines whether the view should wrap horizontally.
`keep-center-on-resize`	`bool`	r/w	Keep the current centered position upon resizing
`kinetic-mode`	`bool`	r/w	Determines whether the view should use kinetic mode.
`latitude`	`float`	r/w	The latitude coordonate of the map
`longitude`	`float`	r/w	The longitude coordonate of the map
`map-source`	`Champlain.MapSource`	r/w	The map source being displayed
`max-zoom-level`	`int`	r/w	The highest allowed level of zoom
`min-zoom-level`	`int`	r/w	The lowest allowed level of zoom
`state`	`Champlain.State`	r	View’s global state
`world`	`Champlain.BoundingBox`	r/w	The bounding box to limit the `Champlain.View` to
`zoom-level`	`int`	r/w	The level of zoom of the map
`zoom-on-double-click`	`bool`	r/w	Zoom in and recenter on double click on the map

Signals¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Short Description
`animation-completed`	The `Champlain.View` `::animation-completed` signal is emitted when any animation in the view ends.
`layer-relocated`	Indicates that the layers have been “relocated”.

Fields¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Type	Access	Description
parent	`Clutter.Actor`	r

Class Details¶

class Champlain.View(**kwargs)¶

Bases:: Clutter.Actor
Abstract:: No
Structure:: Champlain.ViewClass

The Champlain.View structure contains only private data and should be accessed using the provided API

New in version 0.1.

classmethod new()¶

Returns:: a new Champlain.View ready to be used as a Clutter.Actor.
Return type:: Clutter.Actor

Creates an instance of Champlain.View.

New in version 0.4.

add_layer(layer)¶

Parameters:: layer (Champlain.Layer) – a Champlain.Layer

Adds a new layer to the view

New in version 0.2.

add_overlay_source(map_source, opacity)¶

Parameters:

map_source (Champlain.MapSource) – a Champlain.MapSource
opacity (int) – opacity to use

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.

New in version 0.12.5.

bin_layout_add(child, x_align, y_align)¶

Parameters:

child (Clutter.Actor) – The child to be inserted
x_align (Clutter.BinAlignment) – x alignment
y_align (Clutter.BinAlignment) – y alignment

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

New in version 0.10.

Deprecated since version 0.12.4: Use Clutter.ActorAlign and the Clutter.Actor API instead.

center_on(latitude, longitude)¶

Parameters:

latitude (float) – the longitude to center the map at
longitude (float) – the longitude to center the map at

Centers the map on these coordinates.

New in version 0.1.

ensure_layers_visible(animate)¶

Parameters:: animate (bool) – True to perform animation, False otherwise

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

New in version 0.10.

ensure_visible(bbox, animate)¶

Parameters:

bbox (Champlain.BoundingBox) – bounding box of the area that should be visible
animate (bool) – True to perform animation, False otherwise

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

New in version 0.10.

get_animate_zoom()¶

Returns:: True if the view animates zooms, False otherwise.
Return type:: bool

Checks whether the view animates zoom level changes.

New in version 0.12.

get_background_pattern()¶

Returns:: The texture.
Return type:: Clutter.Content

Gets the current background texture displayed behind the map.

New in version 0.12.4.

get_bounding_box()¶

Returns:: the bounding box
Return type:: Champlain.BoundingBox

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

New in version 0.12.4.

get_bounding_box_for_zoom_level(zoom_level)¶

Parameters:: zoom_level (int) – the level of zoom, a int between 1 and 20
Returns:: the bounding box for the view at zoom_level.
Return type:: Champlain.BoundingBox

Gets the bounding box for view self at zoom_level.

New in version 0.12.6.

get_center_latitude()¶

Returns:: the latitude.
Return type:: float

Gets the latitude of the view’s center.

New in version 0.10.

get_center_longitude()¶

Returns:: the longitude.
Return type:: float

Gets the longitude of the view’s center.

New in version 0.10.

get_deceleration()¶

Returns:: the view’s deceleration rate.
Return type:: float

Gets the view’s deceleration rate.

New in version 0.4.

get_horizontal_wrap()¶

Returns:: True if Champlain.View :horizontal-wrap is set.
Return type:: bool

Returns the value of the Champlain.View :horizontal-wrap property.

get_keep_center_on_resize()¶

Returns:: True if the view keeps the center on resize, False otherwise.
Return type:: bool

Checks whether to keep the center on resize

New in version 0.4.

get_kinetic_mode()¶

Returns:: True for kinetic mode, False for push mode.
Return type:: bool

Gets the view’s scroll mode behaviour.

New in version 0.10.

get_license_actor()¶

Returns:: the license actor
Return type:: Champlain.License

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

New in version 0.10.

get_map_source()¶

Returns:: the view’s current map source. If you need to keep a reference to the map source then you have to call GObject.Object.ref().
Return type:: Champlain.MapSource

Gets the view’s current map source.

New in version 0.4.

get_max_zoom_level()¶

Returns:: the view’s maximum allowed zoom level.
Return type:: int

Gets the view’s maximum allowed zoom level.

New in version 0.4.

get_min_zoom_level()¶

Returns:: the view’s minimal allowed zoom level.
Return type:: int

Gets the view’s minimal allowed zoom level.

New in version 0.4.

get_overlay_sources()¶

Returns:: the list
Return type:: [Champlain.MapSource]

Gets a list of overlay sources.

New in version 0.12.5.

get_state()¶

Returns:: the state.
Return type:: Champlain.State

Gets the view’s state.

New in version 0.10.

get_viewport_anchor()¶

Returns:

anchor_x:: the x coordinate of the viewport anchor
anchor_y:: the y coordinate of the viewport anchor

Return type:

(anchor_x: int, anchor_y: int)

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

New in version 0.12.14.

get_viewport_origin()¶

Returns:

x:: the x coordinate of the viewport
y:: the y coordinate of the viewport

Return type:

(x: int, y: int)

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

New in version 0.10.

get_world()¶

Returns:: a Champlain.BoundingBox that represents the current world
Return type:: Champlain.BoundingBox

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

New in version 0.12.11.

get_zoom_level()¶

Returns:: the view’s current zoom level.
Return type:: int

Gets the view’s current zoom level.

New in version 0.4.

get_zoom_on_double_click()¶

Returns:: True if the view zooms on double click, False otherwise.
Return type:: bool

Checks whether the view zooms on double click.

New in version 0.4.

go_to(latitude, longitude)¶

Parameters:

latitude (float) – the longitude to center the map at
longitude (float) – the longitude to center the map at

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

New in version 0.4.

latitude_to_y(latitude)¶

Parameters:: latitude (float) – the latitude
Returns:: the y coordinate
Return type:: float

Converts the latitude to view’s y coordinate.

New in version 0.10.

longitude_to_x(longitude)¶

Parameters:: longitude (float) – the longitude
Returns:: the x coordinate
Return type:: float

Converts the longitude to view’s x coordinate.

New in version 0.10.

reload_tiles()¶: Reloads all visible tiles.

New in version 0.8.

remove_layer(layer)¶

Parameters:: layer (Champlain.Layer) – a Champlain.Layer

Removes the given layer from the view

New in version 0.4.1.

remove_overlay_source(map_source)¶

Parameters:: map_source (Champlain.MapSource) – a Champlain.MapSource

Removes an overlay source from Champlain.View.

New in version 0.12.5.

set_animate_zoom(value)¶

Parameters:: value (bool) – a bool

Should the view animate zoom level changes.

New in version 0.12.

set_background_pattern(background)¶

Parameters:: background (Clutter.Content) – The background texture

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

New in version 0.12.4.

set_deceleration(rate)¶

Parameters:: rate (float) – a float between 1.001 and 2.0

The deceleration rate for the kinetic mode.

New in version 0.4.

set_horizontal_wrap(wrap)¶

Parameters:: wrap (bool) – True to enable horizontal wrapping

Sets the value of the Champlain.View :horizontal-wrap property.

set_keep_center_on_resize(value)¶

Parameters:: value (bool) – a bool

Keep the current centered position when resizing the view.

New in version 0.4.

set_kinetic_mode(kinetic)¶

Parameters:: kinetic (bool) – True for kinetic mode, False for push mode

Determines the way the view reacts to scroll events.

New in version 0.10.

set_map_source(map_source)¶

Parameters:: map_source (Champlain.MapSource) – a Champlain.MapSource

Changes the currently used map source. GObject.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.

New in version 0.4.

set_max_zoom_level(zoom_level)¶

Parameters:: zoom_level (int) – the level of zoom

Changes the highest allowed level of zoom

New in version 0.4.

set_min_zoom_level(zoom_level)¶

Parameters:: zoom_level (int) – the level of zoom

Changes the lowest allowed level of zoom

New in version 0.4.

set_world(bbox)¶

Parameters:: bbox (Champlain.BoundingBox) – the Champlain.BoundingBox of the world

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.

New in version 0.12.11.

set_zoom_level(zoom_level)¶

Parameters:: zoom_level (int) – the level of zoom, a int between 1 and 20

Changes the current level of zoom

New in version 0.4.

set_zoom_on_double_click(value)¶

Parameters:: value (bool) – a bool

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

New in version 0.4.

stop_go_to()¶: Stop the go to animation. The view will stay where it was when the animation was stopped.

New in version 0.4.

to_surface(include_layers)¶

Parameters:: include_layers (bool) – Set to True if you want to include layers
Returns:: a cairo.Surface or None on failure. Free with cairo_surface_destroy() when done.
Return type:: cairo.Surface

Will generate a cairo.Surface that represents the current view of the map. Without any markers or layers. If the current Champlain.Renderer used does not support this, this function will return None.

If include_layers is set to True all layers that implement Champlain.Exportable will be included in the surface.

The Champlain.View also need to be in Champlain.State.DONE state.

x_to_longitude(x)¶

Parameters:: x (float) – x coordinate of the view
Returns:: the longitude
Return type:: float

Converts the view’s x coordinate to longitude.

New in version 0.10.

y_to_latitude(y)¶

Parameters:: y (float) – y coordinate of the view
Returns:: the latitude
Return type:: float

Converts the view’s y coordinate to latitude.

New in version 0.10.

zoom_in()¶: Zoom in the map by one level.

New in version 0.1.

zoom_out()¶: Zoom out the map by one level.

New in version 0.1.

Signal Details¶

Champlain.View.signals.animation_completed(view)¶

Signal Name:: animation-completed
Flags:: RUN_LAST, DETAILED
Parameters:: view (Champlain.View) – The object which received the signal

The Champlain.View ::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”.

New in version 0.4.

Champlain.View.signals.layer_relocated(view)¶

Signal Name:: layer-relocated
Flags:: RUN_LAST
Parameters:: view (Champlain.View) – The object which received the signal

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.

New in version 0.10.

Property Details¶

Champlain.View.props.animate_zoom¶

Name:: animate-zoom
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

Animate zoom change when zooming in/out.

New in version 0.12.

Champlain.View.props.background_pattern¶

Name:: background-pattern
Type:: Clutter.Actor
Default Value:: None
Flags:: READABLE, WRITABLE

The pattern displayed in the background of the map.

New in version 0.12.4.

Champlain.View.props.deceleration¶

Name:: deceleration
Type:: float
Default Value:: 1.1
Flags:: READABLE, WRITABLE

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

New in version 0.10.

Champlain.View.props.goto_animation_duration¶

Name:: goto-animation-duration
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

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.

Champlain.View.props.goto_animation_mode¶

Name:: goto-animation-mode
Type:: Clutter.AnimationMode
Default Value:: Clutter.AnimationMode.EASE_IN_OUT_CIRC
Flags:: READABLE, WRITABLE

The mode of animation when going to a location.

Please note that animation of Champlain.View.ensure_visible also involves a ‘goto’ animation.

Champlain.View.props.horizontal_wrap¶

Name:: horizontal-wrap
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Determines whether the view should wrap horizontally.

Champlain.View.props.keep_center_on_resize¶

Name:: keep-center-on-resize
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

Keep the current centered position when resizing the view.

New in version 0.2.7.

Champlain.View.props.kinetic_mode¶

Name:: kinetic-mode
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Determines whether the view should use kinetic mode.

New in version 0.10.

Champlain.View.props.latitude¶

Name:: latitude
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE

The latitude coordonate of the map

New in version 0.1.

Champlain.View.props.longitude¶

Name:: longitude
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE

The longitude coordonate of the map

New in version 0.1.

Champlain.View.props.map_source¶

Name:: map-source
Type:: Champlain.MapSource
Default Value:: None
Flags:: READABLE, WRITABLE

The Champlain.MapSource being displayed

New in version 0.2.

Champlain.View.props.max_zoom_level¶

Name:: max-zoom-level
Type:: int
Default Value:: 20
Flags:: READABLE, WRITABLE

The highest allowed level of zoom of the content.

New in version 0.4.

Champlain.View.props.min_zoom_level¶

Name:: min-zoom-level
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The lowest allowed level of zoom of the content.

New in version 0.4.

Champlain.View.props.state¶

Name:: state
Type:: Champlain.State
Default Value:: Champlain.State.NONE
Flags:: READABLE

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

New in version 0.4.

Champlain.View.props.world¶

Name:: world
Type:: Champlain.BoundingBox
Default Value:: None
Flags:: READABLE, WRITABLE

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.

New in version 0.12.11.

Champlain.View.props.zoom_level¶

Name:: zoom-level
Type:: int
Default Value:: 3
Flags:: READABLE, WRITABLE

The level of zoom of the content.

New in version 0.1.

Champlain.View.props.zoom_on_double_click¶

Name:: zoom-on-double-click
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

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

New in version 0.4.