Class: Style

H .map .render .webgl.Style

new H.map.render.webgl.Style (config, opt_baseUrl)

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.

`import`

The YAML configuration can contain an optional top-level import element, declaring an import parameter. The value can be a single URL like import: colors.yaml, or an array of URLs import: [a.yaml, b.yaml].

The import block allows to import one or more additional files (which can then in turn recursively import others). It works by deep-merging each imported scene into the current one: the "child" (imported) file is merged first, with the "parent" file merged after, overwriting any properties shared with the child.

The final style configuration is a JavaScript object as a result of merging the master style on top of all the imported styles following the order in which they are listed in the import.

Objects vs. Arrays

One important aspect of the merge behavior is that it applies to all YAML maps/JS objects, but not to YAML sequences/JS arrays. While key/value objects are merged (with new keys inserted, and existing keys overwriting the previous value), arrays are treated as scalar values that entirely overwrite the previous value (rather than merging the array contents).

Relative URLs

The relative URLs of the resources of the imported files are resolved relatively to the hosting location of that file. The optional opt_baseUrl is applied to the master file only.

Name	Type	Description
`config`	string \| H.map.render.webgl.StyleConfig	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:

if the specified configuration is invalid.

Extends

H.map.render.Style

Methods

H.map.render.webgl.Style.normalize (config, baseUrl) static

Normalize properties which can potentially hold relative URLs with the specified style config For example when A.yaml imports B.yaml, relative URLs in B should be resolved from the location of the B.yaml, rather then A.yaml.

Name	Type	Description
`config`	H.map.render.webgl.StyleConfig	The YAML config
`baseUrl`	string	The base URL to use for resolving relative resources

addEventListener (type, handler, opt_capture, opt_scope) inherited

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.

Name	Type	Description
`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

addOnDisposeCallback (callback, opt_scope) inherited

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

Name	Type	Description
`callback`	function	The callback function.
`opt_scope`	Object	optional An optional scope for the callback function

dispatchEvent (evt) inherited

This method dispatches an event on the EventTarget object.

Name	Type	Description
`evt`	H.util.Event \| string	An object representing the event or a string with the event name

dispose () inherited

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.

extractConfig (layerIds, opt_preserving, opt_excludeParentDraws)H.map.render.webgl.StyleConfig

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.render.webgl.Style with only that data layers.

Note that the copy of the configuration is returned.

Name	Type	Description
`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.

Throws:

if any of the layers couldn't be resolved.

Returns:

Type	Description
H.map.render.webgl.StyleConfig	the style configuration for the extracted layers.

getBaseUrl ()string | undefined inherited overrides

Returns the style base URL.

Returns:

Type	Description
string \| undefined

getConfig ()H.map.render.webgl.StyleConfig inherited overrides

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:

Type	Description
H.map.render.webgl.StyleConfig

getProperty (path)*

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

Note that the copy of the configuration is returned.

Name	Type	Description
`path`	string	The `.` delimited property path within the style configuration.

Throws:

if current style state is not READY

Returns:

Type	Description
*	The value of the property or `undefined` if it is not found.

getState ()H.map.render.Style.State inherited

Returns the state of the current style.

Returns:

Type	Description
H.map.render.Style.State

load () inherited overrides

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

mergeConfig (config)

Merges the specified style configuration with the current one.

Name	Type	Description
`config`	H.map.render.webgl.StyleConfig	An object describing the rendering style.

Throws:

in case of an invalid config

Type

H.lang.InvalidArgumentError
if current style state is not READY.

Type

H.lang.IllegalOperationError

removeEventListener (type, handler, opt_capture, opt_scope) inherited

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

Name	Type	Description
`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 object defining the scope for the handler function

removeProperty (path)

Removes the property specified by the . delimited path.

Name	Type	Description
`path`	string	The `.` delimited property path within the style configuration.

Throws:

if current style state is not READY

setInteractive (layerIds, interactive, opt_recursive)

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

Name	Type	Description
`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:

if any of the layers couldn't be resolved.

Example

// Assumption: style has sub data layer "landuse.park"
style.setInteractive('landuse.park', true);

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.

Name	Type	Description
`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:

if current style state is not READY

Type

H.lang.IllegalOperationError
if the specified path exists and is not an Object (aka attempt to create a nested object on a scalar value)

Type

H.lang.InvalidArgumentError

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');

Events

change inherited

Event fired when style changes

Type:

H.util.Event

error inherited

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

Type:

H.util.ErrorEvent