Maps API for JavaScript Developer's Guide

H.map.ViewPort

Class Summary

A viewport object holds information about the HTML element in which the map is rendered. It contains information regarding the size of view port size and triggers events when the size changes.

[ For full details, see the Class Details ]

Property Summary

Table 1. Properties
Properties
`element : {Element}` This property holds the HTML element that defines the viewport.
`width : {number}` This property holds a value indicating the width of the viewport.
`height : {number}` This property holds a value indicating the height of the viewport.
`margin : {number}` This property holds a value indicating the current margin of the viewport.
`padding : {H.map.ViewPort.Padding}` This property holds a value indicating the current padding of the viewport.
`center : {H.math.Point}` This property holds a value indicating the current center point of the viewport.

Method Summary

Table 2. Methods
Methods
`setMargin (margin)` This method sets the margin on the viewport.
`setPadding (top, right, bottom, left)` This method sets a value indicating the padding of the viewport. Padding results in a shifted map center which is the visual center of the padded area.
`resize ()` This method updates the size of the viewport to match the container size. It must be called whenever the HTML element changes size in order to update the map's viewport values.
`startInteraction (modifiers, opt_kinetics)` This method starts the interaction with the view port. It should be called every time a new interaction is started, for example on mouse grab or touch start.
`interaction (x, y, opt_bx, opt_by, opt_timestamp)` This method resolves direct screen (view port) interaction. This function modifies the current view according to values passed in by the caller.
`endInteraction (opt_preventKinetics)` This method ends an interaction and applies a kinetic movement if it was specified in a call to `startInteraction()`
`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.

Events Summary

Table 3. Events
Events
`update : {H.util.Event}` Event fired when the properties of the view-port, such as padding, margin or size, change.
`sync : {H.util.Event}` Event fired when the rendered map is synchronized with the properties of the viewport.

Class Description

A viewport object holds information about the HTML element in which the map is rendered. It contains information regarding the size of view port size and triggers events when the size changes.

Constructor Details

H.map.ViewPort(element, opt_options)

Parameters:
element:: {Element}
: The HTML element where the map is to be rendered
opt_options:: {H.map.ViewPort.Options=} [optional]
: Optional configuration parameters

Property Details

element: {Element}

This property holds the HTML element that defines the viewport.

width: {number}

This property holds a value indicating the width of the viewport.

height: {number}

This property holds a value indicating the height of the viewport.

margin: {number}

This property holds a value indicating the current margin of the viewport.

padding: {H.map.ViewPort.Padding}

This property holds a value indicating the current padding of the viewport.

center: {H.math.Point}

This property holds a value indicating the current center point of the viewport.

Method Details

setMargin (margin)

This method sets the margin on the viewport.

Parameters:
margin:: {number}
: A value indicating the margin used to fetch map data

setPadding (top, right, bottom, left)

This method sets a value indicating the padding of the viewport. Padding results in a shifted map center which is the visual center of the padded area.

Parameters:
top:: {number}
: A value indicating padding at the top of the viewport
right:: {number}
: A value indicating padding on the right of the viewport
bottom:: {number}
: A value indicating padding at the bottom of the viewport
left:: {number}
: A value indicating padding on the left of the viewport

resize ()

This method updates the size of the viewport to match the container size. It must be called whenever the HTML element changes size in order to update the map's viewport values.

startInteraction (modifiers, opt_kinetics)

This method starts the interaction with the view port. It should be called every time a new interaction is started, for example on mouse grab or touch start.

Parameters:
modifiers:: {H.math.BitMask}
: Specifies what operations should performed during every interaction. See H.map.render.RenderEngine.InteractionModifiers
opt_kinetics:: {H.util.kinetics.IKinetics=} [optional]
: Specifies a kinetic move at the end of interaction

interaction (x, y, opt_bx, opt_by, opt_timestamp)

This method resolves direct screen (view port) interaction. This function modifies the current view according to values passed in by the caller.

Parameters:
x:: {number}
: viewport x coordinate
y:: {number}
: viewport y coordinate
opt_bx:: {number=} [optional]
: x coordinate for the second pointer/touch if present
opt_by:: {number=} [optional]
: y coordinate for the second pointer/touch if present
opt_timestamp:: {number=} [optional]
: A known timestamp to use

endInteraction (opt_preventKinetics)

This method ends an interaction and applies a kinetic movement if it was specified in a call to startInteraction()

Parameters:
opt_preventKinetics:: {boolean=} [optional]
: A value indicating a kinetic movement at the end of the interaction is to be prevented (true or not false)

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

Event Details

update: {H.util.Event}

Event fired when the properties of the view-port, such as padding, margin or size, change.

sync: {H.util.Event}

Event fired when the rendered map is synchronized with the properties of the viewport.