Champlain.View

g Atk.ImplementorIface Atk.ImplementorIface Clutter.Actor Clutter.Actor Atk.ImplementorIface->Clutter.Actor Champlain.View Champlain.View Clutter.Actor->Champlain.View Clutter.Animatable Clutter.Animatable Clutter.Animatable->Clutter.Actor Clutter.Container Clutter.Container Clutter.Container->Clutter.Actor Clutter.Scriptable Clutter.Scriptable Clutter.Scriptable->Clutter.Actor GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface GObject.GInterface->Clutter.Animatable GObject.GInterface->Clutter.Container GObject.GInterface->Clutter.Scriptable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Clutter.Actor GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned

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

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:

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:

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:

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.