annotationLayer

geo. annotationLayer

new annotationLayer(argopt) → {geo.annotationLayer}

Description:

  • Layer to handle direct interactions with different features. Annotations (features) can be created by calling mode() or cancelled with mode(null). There is also an "edit" mode which is used when modifying an annotation.

Source:
Parameters:
Name Type Attributes Description
arg geo.annotationLayer.spec <optional>

Specification for the new layer.
Fires:
Returns:
Type
geo.annotationLayer

Extends

Members

idle

Description:

  • Getter for the idle state. Read only.

Source:
Inherited From:
Properties:
Name Type Description
idle boolean

true if the object is idle (onIdle would call a handler immediately).

Getter for the idle state. Read only.

(protected) newLayerId

Description:

  • Gets a new id number for a layer.

Source:
Inherited From:

Gets a new id number for a layer.

Methods

active(argopt) → {boolean|this}

Description:

  • Get/Set whether or not the layer is active. An active layer will receive native mouse when the layer is on top. Non-active layers will never receive native mouse events.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
arg boolean <optional>

If specified, the new active value.
Returns:
Type
boolean | this

addAnnotation(annotation, gcsopt, updateopt) → {this}

Description:

  • Add an annotation to the layer. The annotation could be in any state.

Source:
Parameters:
Name Type Attributes Description
annotation geo.annotation

The annotation to add.
gcs string | geo.transform | null <optional>

undefined to use the interface gcs, null to use the map gcs, or any other transform.
update boolean <optional>

If false, don't update the layer after adding the annotation.
Fires:
Returns:

The current layer.

Type
this

addChild(child) → {this}

Description:

  • Add a child (or an array of children) to the object.

Source:
Inherited From:
Parameters:
Name Type Description
child geo.object | Array.<geo.object>

A child object or array of child objects.
Returns:
Type
this

addFeature(feature) → {this}

Description:

  • Add a feature to the layer if it is not already present.

Source:
Inherited From:
Parameters:
Name Type Description
feature object

the feature to add.
Returns:
Type
this

addPromise(promise) → {this}

Description:

  • Add the promise here and also propagate up the scene tree.

Source:
Inherited From:
Parameters:
Name Type Description
promise Promise

A promise object.
Returns:
Type
this

annotationById(id) → {geo.annotation}

Description:

  • Get an annotation by its id.

Source:
Parameters:
Name Type Description
id number

The annotation ID.
Returns:

The selected annotation or undefined if none matches the id.

Type
geo.annotation

annotations() → {Array.<geo.annotation>}

Description:

  • Get the list of annotations on the layer.

Source:
Returns:

An array of annotations.

Type
Array.<geo.annotation>

attribution(argnullable) → {string|this}

Description:

  • Get or set the attribution html content that will displayed with the layer. By default, nothing will be displayed. Note, this content is not html escaped, so care should be taken when rendering user provided content.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
arg string <nullable>

An html fragment
Returns:

Chainable as a setter

Type
string | this

autoshareRenderer() → {boolean|string}

Description:

  • Get the setting of autoshareRenderer.

Source:
Inherited From:
Returns:
Type
boolean | string

canvas() → {HTMLCanvasElement}

Description:

  • Get canvas of the layer.

Source:
Inherited From:
Returns:

The canvas element associated with the layer.

Type
HTMLCanvasElement

children() → {Array.<geo.object>}

Description:

  • Get an array of the child objects.

Source:
Inherited From:
Returns:

A copy of the array of child objects.

Type
Array.<geo.object>

clear() → {this}

Description:

  • Clear all features in layer.

Source:
Inherited From:
Returns:
Type
this

createFeature(featureName, arg) → {geo.feature}

Description:

  • Create a feature by name.

Source:
Inherited From:
Parameters:
Name Type Description
featureName string

The name of the feature to create.
arg object

Properties for the new feature.
Returns:

The created feature.

Type
geo.feature

currentBooleanOperation() → (nullable) {string}

Description:

  • Check if there is a current boolean operation.

Source:
Returns:

Either undefined for no current boolean operation or the name of the operation.

Type
string

dataTime() → {geo.timestamp}

Description:

  • Return last time data got changed.

Source:
Inherited From:
Returns:

The data time.

Type
geo.timestamp

deleteFeature(feature) → {this}

Description:

  • Delete feature.

Source:
Inherited From:
Parameters:
Name Type Description
feature geo.feature

The feature to delete.
Returns:
Type
this

displayDistance(coord1, gcs1, coord2, gcs2opt) → {number}

Description:

  • Calculate the display distance for two coordinate in the current map.

Source:
Parameters:
Name Type Attributes Description
coord1 geo.geoPosition | geo.screenPosition

The first coordinates.
gcs1 string | geo.transform | null

undefined to use the interface gcs, null to use the map gcs, 'display' if the coordinates are already in display coordinates, or any other transform.
coord2 geo.geoPosition | geo.screenPosition

the second coordinates.
gcs2 string | geo.transform | null <optional>

undefined to use the interface gcs, null to use the map gcs, 'display' if the coordinates are already in display coordinates, or any other transform.
Returns:

the Euclidean distance between the two coordinates.

Type
number

draw() → {this}

Description:

  • Update if necessary and draw the layer.

Source:
Overrides:
Returns:

The current layer.

Type
this

features(valopt) → {Array.<geo.feature>|this}

Description:

  • Get/Set drawables.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val Array.<geo.feature> <optional>

A list of features, or unspecified to return the current feature list. If a list is provided, features are added or removed as needed.
Returns:

The current features associated with the layer or the current layer.

Type
Array.<geo.feature> | this

fromLocal(input) → {geo.geoPosition}

Description:

  • Transform coordinates from a local coordinate system to world coordinates.

Source:
Inherited From:
Parameters:
Name Type Description
input geo.geoPosition

Renderer coordinates.
Returns:

World coordinates.

Type
geo.geoPosition

fromPolygonList(poly, optsopt) → {this}

Description:

  • Replace appropriate annotations with a list of polygons.

Source:
Parameters:
Name Type Attributes Description
poly geo.polygonList

A list of polygons.
opts geo.util.polyop.annotationLayerSpec <optional>

This contains annotationIndices and correspondence used to track annotations.
Returns:
Type
this

gcsFeatures(valopt, nullable) → {string|this}

Description:

  • Get or set the gcs for all features. For features, the default is usually the map's ingcs.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val string <optional>
<nullable>

If undefined, return the current gcs. If null, use the map's interface gcs. Otherwise, set a new value for the gcs. When getting the current gcs, if not all features have the same gcs, undefined will be returned.
Returns:

A string used by geo.transform. If the map interface gcs is in use, that value will be returned. If the gcs is set, return the current class instance.

Type
string | this

geoIsOn(event, handleropt) → {boolean}

Description:

  • Report if an event handler is bound to this object.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
event string | Array.<string>

An event or list of events to check.
handler function <optional>

A function that might be bound. If undefined, this will report true if there is any handler for the specified event.
Returns:

true if any of the specified events are bound to the specified handler.

Type
boolean

geoOff(eventopt, argopt, nullable) → {this}

Description:

  • Remove handlers from one event or an array of events. If no event is provided all handlers will be removed.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
event string | Array.<string> <optional>

An event or a list of events from geo.event or defined by the user, or undefined to remove all events (in which case arg is ignored).
arg function | Array.<function()> <optional>
<nullable>

A function or array of functions to remove from the events or a falsy value to remove all handlers from the events.
Returns:
Type
this

geoOn(event, handler) → {this}

Description:

  • Bind an event handler to this object.

Source:
Inherited From:
Parameters:
Name Type Description
event string

An event from geo.event or a user-defined value.
handler function

A function that is called when event is triggered. The function is passed a geo.event object.
Returns:
Type
this

geoOnce(event, handler) → {function}

Description:

  • Bind an event handler to this object that will fire once and then deregister itself.

Source:
Inherited From:
Parameters:
Name Type Description
event string

An event from geo.event or a user-defined value.
handler function

A function that is called when event is triggered. The function is passed a geo.event object.
Returns:

The actual bound handler. This is a wrapper around the handler that was passed to the function.

Type
function

geoTrigger(event, args, childrenOnlyopt) → {this}

Description:

  • Trigger an event (or events) on this object and call all handlers.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
event string

The event to trigger.
args object

Arbitrary argument to pass to the handler.
childrenOnly boolean <optional>

If truthy, only propagate down the tree.
Returns:
Type
this

geojson(geojsonopt, clearopt, gcsopt, includeCrsopt) → {object|number|undefined}

Description:

  • Return the current set of annotations as a geojson object. Alternately, add a set of annotations from a geojson object.

Source:
Parameters:
Name Type Attributes Description
geojson string | object | File <optional>

If present, add annotations based on the given geojson object. If undefined, return the current annotations as geojson. This may be a JSON string, a javascript object, or a File object.
clear boolean | string <optional>

If true, when adding annotations, first remove all existing objects. If 'update', update existing annotations and remove annotations that no longer exist. If falsy, update existing annotations and leave annotations that have not changed.
gcs string | geo.transform | null <optional>

undefined to use the interface gcs, null to use the map gcs, or any other transform.
includeCrs boolean <optional>

If truthy, include the coordinate system in the output.
Returns:

If geojson was undefined, the current annotations is a javascript object that can be converted to geojson using JSON.stringify. If geojson is specified, either the number of annotations now present upon success, or undefined if the value in geojson was not able to be parsed.

Type
object | number | undefined

height() → {number}

Description:

  • Return the height of the layer in pixels.

Source:
Inherited From:
Returns:

The height of the parent map in pixels.

Type
number

id(valopt) → {string|this}

Description:

  • Get/Set id of the layer.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val string | null <optional>

If null, generate a new layer id. Otherwise, if specified, the new id of the layer.
Returns:
Type
string | this

initialized(valopt) → {boolean|this}

Description:

  • Get/Set if the layer has been initialized.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val boolean <optional>

If specified, update the initialized value. Otherwise, return the current instance.
Returns:

Either the initialized value or this.

Type
boolean | this

map() → {geo.map}

Description:

  • Get the map associated with this layer.

Source:
Inherited From:
Returns:

The map associated with the layer.

Type
geo.map

mode(argopt, editAnnotationopt, optionsopt) → {string|null|this}

Description:

  • Get or set the current mode.

Source:
Parameters:
Name Type Attributes Description
arg string | null <optional>

undefined to get the current mode, null to stop creating/editing, this.modes.edit ('edit') plus an annotation to switch to edit mode, this.modes.cursor plus an annotation to switch to using the annotation as a cursor, or the name of the type of annotation to create. Available annotations can listed via geo.listAnnotations.
editAnnotation geo.annotation <optional>

If arg === this.modes.edit or arg === this.modes.cursor, this is the annotation that should be edited or used.
options object <optional>

Additional options to pass when creating an annotation.
Fires:
Returns:

The current mode or the layer.

Type
string | null | this

modified() → {this}

Description:

  • Update the timestamp to the next global timestamp value.

Source:
Inherited From:
Returns:
Type
this

moveDown(nopt) → {this}

Description:

  • Bring the layer below the given number of layers. This will rotate the current z-indices for this and the previous n layers.

Source:
Inherited From:
Parameters:
Name Type Attributes Default Description
n number <optional>
 1

The number of positions to move.
Returns:
Type
this

moveToBottom() → {this}

Description:

  • Bring the layer to the bottom of the map layers.

Source:
Inherited From:
Returns:
Type
this

moveToTop() → {this}

Description:

  • Bring the layer to the top of the map layers.

Source:
Inherited From:
Returns:
Type
this

moveUp(nopt) → {this}

Description:

  • Bring the layer above the given number of layers. This will rotate the current z-indices for this and the next n layers.

Source:
Inherited From:
Parameters:
Name Type Attributes Default Description
n number <optional>
 1

The number of positions to move.
Returns:
Type
this

name(valopt) → {string|this}

Description:

  • Get/Set name of the layer.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val string <optional>

If specified, the new name of the layer.
Returns:
Type
string | this

node() → {HTMLDivElement}

Description:

  • Get root node of the layer.

Source:
Inherited From:
Returns:
Type
HTMLDivElement

onIdle(handler) → {this}

Description:

  • Bind a handler that will be called one time when all internal promises are resolved. If there are no outstanding promises, this is invoked synchronously.

Source:
Inherited From:
Parameters:
Name Type Description
handler function

A function taking no arguments.
Returns:
Type
this

opacity(opacityopt) → {number|this}

Description:

  • Get or set the current layer opacity. The opacity is in the range [0-1]. An opacity of 0 is not the same as setting visible(false), as interactions can still occur with the layer.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
opacity number <optional>

If specified, set the opacity. Otherwise, return the opacity.
Returns:

The current opacity or the current layer.

Type
number | this

options(arg1opt, arg2opt) → {object|this}

Description:

  • Set or get options.

Source:
Parameters:
Name Type Attributes Description
arg1 string | object <optional>

If undefined, return the options object. If a string, either set or return the option of that name. If an object, update the options with the object's values.
arg2 object <optional>

If arg1 is a string and this is defined, set the option to this value.
Returns:

If options are set, return the annotation, otherwise return the requested option or the set of options.

Type
object | this

parent(argopt) → {this|geo.sceneObject}

Description:

  • Get/set parent of the object.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
arg geo.sceneObject <optional>

The new parent or undefined to get the current parent.
Returns:
Type
this | geo.sceneObject

removeAllAnnotations(skipCreatingopt, updateopt) → {number}

Description:

  • Remove all annotations from the layer.

Source:
Parameters:
Name Type Attributes Description
skipCreating boolean <optional>

If truthy, don't remove annotations that are in the create state.
update boolean <optional>

If false, don't update the layer after removing the annotation.
Returns:

The number of annotations that were removed.

Type
number

removeAnnotation(annotation, updateopt, posopt) → {boolean}

Description:

  • Remove an annotation from the layer.

Source:
Parameters:
Name Type Attributes Description
annotation geo.annotation

The annotation to remove.
update boolean <optional>

If false, don't update the layer after removing the annotation.
pos int <optional>

The posiiton of the annotation in the annotation list, if known. This speeds up the process.
Fires:
Returns:

true if an annotation was removed.

Type
boolean

removeChild(child) → {this}

Description:

  • Remove a child (or array of children) from the object.

Source:
Inherited From:
Parameters:
Name Type Description
child geo.object | Array.<geo.object>

A child object or array of child objects.
Returns:
Type
this

removeFeature(feature) → {this}

Description:

  • Remove a feature without destroying it.

Source:
Inherited From:
Parameters:
Name Type Description
feature geo.feature

The feature to remove.
Returns:
Type
this

removePromise(promise) → {this}

Description:

  • Remove the promise here and also propagate up the scene tree.

Source:
Inherited From:
Parameters:
Name Type Description
promise Promise

A promise object.
Returns:
Type
this

renderer() → {geo.renderer}

Description:

  • Get the renderer for the layer.

Source:
Inherited From:
Returns:

The renderer associated with the layer or null if there is no renderer.

Type
geo.renderer

rendererName() → {string}

Description:

  • Get the name of the renderer.

Source:
Inherited From:
Returns:
Type
string

selectionAPI(valopt) → {boolean|this}

Description:

  • Get/Set selectionAPI of the layer.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val boolean <optional>

If specified change the selectionAPI state of the layer, otherwise return the current state.
Returns:

The selectionAPI state or the current layer.

Type
boolean | this

sticky() → {boolean}

Description:

  • Get whether or not the layer is sticky (navigates with the map).

Source:
Inherited From:
Returns:
Type
boolean

timestamp() → {number}

Description:

  • Get time.

Source:
Inherited From:
Returns:

The timestamp. This is 0 if the timestamp has never been modified.

Type
number

toLocal(input) → {geo.geoPosition}

Description:

  • Transform coordinates from world coordinates into a local coordinate system specific to the underlying renderer. This method is exposed to allow direct access the rendering context, but otherwise should not be called directly. The default implementation is the identity operator.

Source:
Inherited From:
Parameters:
Name Type Description
input geo.geoPosition

World coordinates.
Returns:

Renderer coordinates.

Type
geo.geoPosition

toPolygonList(optsopt) → {geo.polygonList}

Description:

  • Return any annotation that has area as a polygon list: an array of polygons, each of which is an array of polylines, each of which is an array of points, each of which is a 2-tuple of numbers.

Source:
Parameters:
Name Type Attributes Description
opts geo.util.polyop.spec <optional>

Ignored.
Returns:

A list of polygons.

Type
geo.polygonList

updateTime() → {geo.timestamp}

Description:

  • Return the modified time for the last update that did something.

Source:
Inherited From:
Returns:

The update time.

Type
geo.timestamp

validateAttribute(value, dataType) → {number|string|object|boolean|undefined}

Description:

  • Validate a value for an attribute based on a specified data type. This returns a sanitized value or undefined if the value was invalid. Data types include:

    • color: a css string, #rrggbb hex string, #rgb hex string, number, or object with r, g, b properties in the range of [0-1].
    • opacity: a floating point number in the range [0, 1].
    • positive: a floating point number greater than zero.
    • boolean: a string whose lowercase value is 'false', 'off', or 'no', and falsy values are false, all else is true. null and undefined are still considered invalid values.
    • booleanOrNumber: a string whose lowercase value is 'false', 'off', 'no', 'true', 'on', or 'yes', falsy values that aren't 0, and true are handled as booleans. Otherwise, a floating point number that isn't NaN or an infinity.
    • coordinate2: either an object with x and y properties that are numbers, or a string of the form [,] with optional whitespace, or a JSON encoded object with x and y values, or a JSON encoded list of at leasst two numbers.
    • number: a floating point number that isn't NaN or an infinity.
    • angle: a number that represents radians. If followed by one of deg, grad, or turn, it is converted to radians. An empty string is also allowed.
    • text: any text string.
Source:
Parameters:
Name Type Description
value number | string | object | boolean

The value to validate.
dataType string

The data type for validation.
Returns:

The sanitized value or undefined.

Type
number | string | object | boolean | undefined

visible(valopt) → {boolean|this}

Description:

  • Get/Set visibility of the layer.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
val boolean <optional>

If specified, change the visibility, otherwise return it.
Returns:

The current visibility or the layer.

Type
boolean | this

width() → {number}

Description:

  • Return the width of the layer in pixels.

Source:
Inherited From:
Returns:

The width of the parent map in pixels.

Type
number

zIndex(zIndexopt, allowDuplicateopt) → {number|this}

Description:

  • Get or set the z-index of the layer. The z-index controls the display order of the layers in much the same way as the CSS z-index property.

Source:
Inherited From:
Parameters:
Name Type Attributes Description
zIndex number <optional>

The new z-index, or undefined to return the current z-index.
allowDuplicate boolean <optional>

When setting the z index, if this is truthy, allow other layers to have the same z-index. Otherwise, ensure that other layers have distinct z-indices from this one.
Returns:
Type
number | this

Type Definitions

labelRecord

Source:
Properties:
Name Type Attributes Description
text string

The text of the label
position geo.geoPosition

The position of the label in map gcs coordinates.
style geo.textFeature.styleSpec <optional>

A geo.textFeature style object.
Type:
  • object

spec

Description:

  • Object specification for an annotation layer.

Source:
Properties:
Name Type Attributes Default Description
dblClickTime number <optional>
 300

The delay in milliseconds that is treated as a double-click when working with annotations.
adjacentPointProximity number <optional>
 5

The minimum distance in display coordinates (pixels) between two adjacent points when creating a polygon or line. A value of 0 requires an exact match.
continuousPointProximity number <optional>
 5

The minimum distance in display coordinates (pixels) between two adjacent points when dragging to create an annotation. false disables continuous drawing mode.
continuousPointCollinearity number <optional>
 1.0deg

The minimum angle between a series of three points when dragging to not interpret them as collinear. Only applies if continuousPointProximity is not false.
continuousCloseProximity number <optional>
 10

The minimum distance in display coordinates (pixels) to close a polygon or end drawing a line when dragging to create an annotation. false never closes at the end of a drag. true is effectively infinite.
finalPointProximity number <optional>
 10

The maximum distance in display coordinates (pixels) between the starting point and the mouse coordinates to signal closing a polygon. A value of 0 requires an exact match. A negative value disables closing a polygon by clicking on the start point.
showLabels boolean <optional>
 true

Truthy to show feature labels that are allowed by the associated feature to be shown.
clickToEdit boolean <optional>
 false

Truthy to allow clicking an annotation to place it in edit mode.
defaultLabelStyle geo.textFeature.styleSpec <optional>

Default styles for labels.
id number <optional>

The id of the layer. Defaults to a increasing sequence.
map geo.map <optional>
 null

Parent map of the layer.
renderer string | geo.renderer <optional>

Renderer to associate with the layer. If not specified, either annotations or features can be used to determine the renderer. If a geo.renderer instance, the renderer is not recreated; not all renderers can be shared by multiple layers.
autoshareRenderer boolean | string <optional>
 true

If truthy and the renderer supports it, auto-share renderers between layers. Currently, auto-sharing can only occur for webgl renderers and adjacent layers. If true, sharing will only occur if the layers have the same opacity and it is 1 or 0 and any tile layers are below non-tile layers. If "more", sharing will occur for any adjacent layers that have the same opacity. Shared renderers has slightly different behavior than non-shared renderers: changing z-index may result in rerendering and be slightly slower; only one DOM canvas is used for all shared renderers. Some features have slight z-stacking differences in shared versus non-shared renderers.
canvas HTMLElement <optional>

If specified, use this canvas rather than a canvas associaied with the renderer directly. Renderers may not support sharing a canvas.
annotations Array.<string> | object <optional>

A list of annotations that will be used on this layer, used to select a renderer. Instead of a list, if this is an object, the keys are the annotation names, and the values are each a list of modes that will be used with that annotation. See featuresForAnnotations more details. This is ignored if renderer is specified.
features Array.<string> <optional>

A list of features that will be used on this layer, used to select a renderer. Features are the basic feature names (e.g., 'quad'), or the feature name followed by a required capability (e.g., 'quad.image'). This is ignored if renderer or annotations is specified.
active boolean <optional>
 true

Truthy if the layer has the active css class and may receive native mouse events.
attribution string <optional>

An attribution string to display.
opacity number <optional>
 1

The layer opacity on a scale of [0-1].
name string <optional>
 ''

A name for the layer for user convenience. If specified, this is also the id property of the containing DOM element.
selectionAPI boolean <optional>
 true

Truthy if the layer can generate selection and other interaction events.
sticky boolean <optional>
 true

Truthy if the layer should navigate with the map.
visible boolean <optional>
 true

Truthy if the layer is visible.
zIndex number <optional>

The z-index to assign to the layer (defaults to the index of the layer inside the map).

Object specification for an annotation layer.

Type: