Maps API for JavaScript Developer's Guide

H.map.Style

Class Summary

Extends: H.util.EventTarget

Instances of this class hold style configuration for rendering provider data using H.map.render.webgl.RenderEngine. It also provides utility methods for operating with the style.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

getState () : {H.map.Style.State}

Returns the state of the current style.

getBaseUrl () : {(string | undefined)}

Returns the style base URL.

getConfig () : {?Object}

To get the current style configuration as a JavaScript Object, or null if there was an error loading/parsing the style configuration.

load ()

Starts loading the style configuration if it was specified as a URL or parsing the style configuration if it was passed as a YAML formatted string.

setInteractive (layerIds, interactive, opt_recursive)

Enables or disables object picking on objects from the data layers with the specified ids.

setProperty (path, value, opt_force)

Sets the specified value to the property specified by the . delimited path. If property by the specified path does not exist, it is created according to the nesting levels.

getProperty (path) : {*}

Returns the value of the property specified by the . delimited path.

removeProperty (path)

Removes the property specified by the . delimited path.

mergeConfig (config)

Merges the specified style configuration with the current one.

extractConfig (layerIds, opt_preserving, opt_excludeParentDraws) : {Object}

Extracts the style configuration of the data layers with the specified ids. By default extracted layers are removed from the current layer, however that behavior can be changed by passing true as opt_preserving flag. Returned configuration object represents the extracted layers and can be used for creating a new H.map.Style with only that data layers.

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 2. Events
Events

change : {H.util.Event}

Event fired when style changes

error : {H.util.ErrorEvent}

Event fired when error occurs during style load, parsing, etc.

Class Description

Instances of this class hold style configuration for rendering provider data using H.map.render.webgl.RenderEngine. It also provides utility methods for operating with the style.

Specify a URL as a config parameter value to load the YAML formatted style configuration. Note that all relative paths within that configuration (textures, imported sub-styles, fonts, etc.) are resolved relative to the hosting location of the main style. The styles are loaded automatically if a layer with the provider using the style is added to the map. Alternatively load() method can be called explicitly to start the loading when needed. Resulting style configuration can be obtain using the getConfig() method of the class. The returned JavaScript object is the result of merging master style with all the imported styles.

Constructor Details

H.map.Style(config, opt_baseUrl)

Parameters:
 
config:
{(string | Object)}
 
Either a URL to load the style from, YAML formatted string or an object describing the rendering style. The URL can be absolute or relative, but should end with either .yaml or .yml extension.
opt_baseUrl:
{string=} [optional]
 
The base URL to use for resolving relative URLs in the style like textures, fonts. When URL is passed as a config, it is used as a default base URL. Otherwise resources with the relative paths are resolved relative to the page location.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the specified configuration is invalid.

Method Details

getState () : {H.map.Style.State}

Returns the state of the current style.

Returns:
 
{H.map.Style.State}

getBaseUrl () : {(string | undefined)}

Returns the style base URL.

Returns:
 
{(string | undefined)}

getConfig () : {?Object}

To get the current style configuration as a JavaScript Object, or null if there was an error loading/parsing the style configuration.

Note that the copy of the configuration is returned.

Returns:
 
{?Object}

load ()

Starts loading the style configuration if it was specified as a URL or parsing the style configuration if it was passed as a YAML formatted string.

setInteractive (layerIds, interactive, opt_recursive)

Enables or disables object picking on objects from the data layers with the specified ids.

Example

// Assumption: style has sub data layer "landuse.park"
style.setInteractive('landuse.park', true);
Parameters:
 
layerIds:
{(string | Array<string>)}
 
Either a single id or array of ids of the layers to enable/disable object picking. Nested layers ids should be specified using dot as a delimiter like landuse.park.
interactive:
{boolean}
 
Pass true to make layer objects interactive, and false otherwise.
opt_recursive:
{boolean=} [optional]
 
A Boolean value indicating whether sub-layers should be traversed recursively. Default value is true. Pass false to only affect topmost layers, i.e. directly accessible by layerIds.
Throws:
 
{H.lang.InvalidArgumentError}
 
if any of the layers couldn't be resolved.

setProperty (path, value, opt_force)

Sets the specified value to the property specified by the . delimited path. If property by the specified path does not exist, it is created according to the nesting levels.

Example

// Assumption: style has sub data layer "landuse.park" with instructions to draw it as a polygon.
style.setProperty('layers.landuse.park.draw.polygons.color', 'red');
Parameters:
 
path:
{string}
 
The . delimited property path within config to set the value. If the resulting path points to a primitive type value, error will be thrown to prevent incidental overrides unless opt_force parameter is set.
value:
{(string | number | Object | boolean | Array)}
 
The value to set. Note that for performance reasons the value is set by reference.
opt_force:
{boolean=} [optional]
 
Forces overriding of a primitive value (if such is found) along the specified path. For example if the style has a property foo.bar=1, calling style.setProperty('foo.bar.x', 1) will throw an error, whereas style.setProperty('foo.bar.x', 1, true) will override the foo.bar with the value {x: 1}.
Throws:
 
{H.lang.IllegalOperationError}
 
if current style state is not `READY`
{H.lang.InvalidArgumentError}
 
if the specified path exists and is not an `Object` (aka attempt to create a nested object on a scalar value)

getProperty (path) : {*}

Returns the value of the property specified by the . delimited path.

Note that the copy of the configuration is returned.

Parameters:
 
path:
{string}
 
The . delimited property path within the style configuration.
Returns:
 
{*}
The value of the property or undefined if it is not found.
Throws:
 
{H.lang.IllegalOperationError}
 
if current style state is not `READY`

removeProperty (path)

Removes the property specified by the . delimited path.

Parameters:
 
path:
{string}
 
The . delimited property path within the style configuration.
Throws:
 
{H.lang.IllegalOperationError}
 
if current style state is not `READY`

mergeConfig (config)

Merges the specified style configuration with the current one.

Parameters:
 
config:
{Object}
 
An object describing the rendering style.
Throws:
 
{H.lang.InvalidArgumentError}
 
in case of an invalid config
{H.lang.IllegalOperationError}
 
if current style state is not `READY`.

extractConfig (layerIds, opt_preserving, opt_excludeParentDraws) : {Object}

Extracts the style configuration of the data layers with the specified ids. By default extracted layers are removed from the current layer, however that behavior can be changed by passing true as opt_preserving flag. Returned configuration object represents the extracted layers and can be used for creating a new H.map.Style with only that data layers.

Note that the copy of the configuration is returned.

Parameters:
 
layerIds:
{!Array<string>}
 
The IDs of the layers to extract. IDs of nesting parent layers must be placed in front using dot as a delimiter like landuse.park.
opt_preserving:
{boolean=} [optional]
 
Indicates whether the extracted layer are preserved in the given layer.
opt_excludeParentDraws:
{boolean=} [optional]
 
Indicates whether the "draw" properties in parent layers are excluded during extraction.
Returns:
 
{Object}
the style configuration for the extracted layers.
Throws:
 
{H.lang.InvalidArgumentError}
 
if any of the layers couldn't be resolved.

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

change: {H.util.Event}

Event fired when style changes

error: {H.util.ErrorEvent}

Event fired when error occurs during style load, parsing, etc.