Maps API for JavaScript Developer's Guide

H.map.ViewModel

Class Summary

Extends: H.util.EventTarget

Implements: H.map.IControl

This class represents a view of the map. It consists of a look-at point which has a position in geo-space and orientation angles (heading, tilt and incline). The view model allows to change the values of this object in order to move or rotate the map or zoom in and out.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

setLookAtData (data, opt_animate) : {H.map.ViewModel}

To set new look-at data for the view model.

getLookAtData () : {H.map.ViewModel.ILookAtData}

This method retrieves the current rendered look-at data.

startControl (opt_kinetics, opt_atX, opt_atY)

To start the controlling of the look-at-point animation. After this method was invoked, the look-at-point animation can be controlled by several calls of H.map.ViewModel#control and finished by a call of H.map.ViewModel#endControl

control (moveX, moveY, moveZ, rotateX, rotateY, rotateZ)

To control a look-at-point animation in screen space. Before the look-at-point can be controlled the method H.map.ViewModel#startControl must be invoked once. The animation can be finished via H.map.ViewModel#endControl

endControl (opt_preventKinetics, opt_adjustView)

To finish the control of a look-at-point animation. See also H.map.ViewModel#startControl and H.map.ViewModel#control

addEventListener (type, handler, opt_capture, opt_scope)

This method adds a listener for a specific event.

removeEventListener (type, handler, opt_capture, opt_scope)

This method removes a previously added listener from the EventTarget instance.

dispatchEvent (evt)

This method dispatches an event on the EventTarget object.

dispose ()

This method removes listeners from the given object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners.

addOnDisposeCallback (callback, opt_scope)

This method adds a callback which is triggered when the EventTarget object is being disposed.

Class Description

This class represents a view of the map. It consists of a look-at point which has a position in geo-space and orientation angles (heading, tilt and incline). The view model allows to change the values of this object in order to move or rotate the map or zoom in and out.

Modifying the view of a map is asynchronous as the view model notifies the renderer of a change in its state and triggers the renderer.

A map renderer can choose to ignore or even correct certain values depending on its capabilities. For example a 2D map renderer will ignore tilt values and correct tilt values to be 0 on the view model in order to keep the integrity of the view model.

In order to be notified of changes to the model that originate from the renderer, the view model dispatches a "sync" event whenever the renderer synchronizes the requested changes to the view with its own internal state.

Constructor Details

H.map.ViewModel()

Method Details

setLookAtData (data, opt_animate) : {H.map.ViewModel}

To set new look-at data for the view model.

Parameters:
 
data:
{H.map.ViewModel.ILookAtData}
 
The values to be modified. Here are some of the main possibilities to reposition the camera at give look-at point:
  • position - use existing (default) zoom and change map center
  • zoom - use existing (default) map center and change zoom
  • position & zoom - use specified position as map center and zoom
  • bounds - set center of the bounds as a new map center and calculate zoom such that bounds are visible
  • bounds & position - set specified position as map center and calculate zoom such that bounds are visible
  • bounds & zoom - set center of the bounds as a new map center and set specified zoom
  • bounds & position & zoom - ignore bounds and use specified position and zoom
  • tilt, heading, incline - set look-at angles
opt_animate:
{boolean=} [optional]
 
A value indicating if an animated transition should be applied, default is false.
Returns:
 
{H.map.ViewModel}
this view model object

getLookAtData () : {H.map.ViewModel.ILookAtData}

This method retrieves the current rendered look-at data.

Returns:
 
{H.map.ViewModel.ILookAtData}
The current rendered look-at data

startControl (opt_kinetics, opt_atX, opt_atY)

To start the controlling of the look-at-point animation. After this method was invoked, the look-at-point animation can be controlled by several calls of H.map.ViewModel#control and finished by a call of H.map.ViewModel#endControl

Parameters:
 
opt_kinetics:
{H.util.kinetics.IKinetics=} [optional]
 
Kinetics settings
opt_atX:
{number=} [optional]
 
The x screen coordinate at which control starts
opt_atY:
{number=} [optional]
 
The y screen coordinate at which control starts

control (moveX, moveY, moveZ, rotateX, rotateY, rotateZ)

To control a look-at-point animation in screen space. Before the look-at-point can be controlled the method H.map.ViewModel#startControl must be invoked once. The animation can be finished via H.map.ViewModel#endControl

Parameters:
 
moveX:
{number}
 
The movement along the x-axis in pixels per second
moveY:
{number}
 
The movement along the y-axis in pixels per second
moveZ:
{number}
 
The movement along the z-axis in zoom-levels per second
rotateX:
{number}
 
The rotation around the x-axis in degrees per second
rotateY:
{number}
 
The rotation around the y-axis in degrees per second
rotateZ:
{number}
 
The rotation around the z-axis in degrees per second

endControl (opt_preventKinetics, opt_adjustView)

To finish the control of a look-at-point animation. See also H.map.ViewModel#startControl and H.map.ViewModel#control

Example

//prevent kinetics
viewModel.endControl(true);

//prevent kinetics and set adjusted view
viewModel.endControl(true, function(requested) {
  requested.zoom = Math.round(requested.zoom);
});
Parameters:
 
opt_preventKinetics:
{boolean=} [optional]
 
Indicates whether a kinetic effect at the end of the controlled animation is prevented.
opt_adjustView:
{function(H.map.ViewModel.ILookAtData)=} [optional]
 
A custom function to adjust the final view. It receives the last requested look-at data from the view model and has to return a possibly modified H.map.ViewModel.ILookAtData which is used instead.

addEventListener (type, handler, opt_capture, opt_scope)

This method adds a listener for a specific event.

Note that to prevent potential memory leaks, you must either call removeEventListener or dispose on the given object when you no longer need it.

Parameters:
 
type:
{string}
 
The name of the event
handler:
{!Function}
 
An event handler function
opt_capture:
{boolean=} [optional]
 
true indicates that the method should listen in the capture phase (bubble otherwise)
opt_scope:
{Object=} [optional]
 
An object defining the scope for the handler function

removeEventListener (type, handler, opt_capture, opt_scope)

This method removes a previously added listener from the EventTarget instance.

Parameters:
 
type:
{string}
 
The name of the event
handler:
{!Function}
 
A previously added event handler
opt_capture:
{boolean=} [optional]
 
true indicates that the method should listen in the capture phase (bubble otherwise)
opt_scope:
{Object=} [optional]
 
An oject defining the scope for the handler function

dispatchEvent (evt)

This method dispatches an event on the EventTarget object.

Parameters:
 
evt:
{(H.util.Event | string)}
 
An object representing the event or a string with the event name

dispose ()

This method removes listeners from the given object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners.

addOnDisposeCallback (callback, opt_scope)

This method adds a callback which is triggered when the EventTarget object is being disposed.

Parameters:
 
callback:
{!Function}
 
The callback function.
opt_scope:
{Object=} [optional]
 
An optional scope for the callback function