Maps SDK for Web - Maps.GeolocateControl

tt.GeolocateControl

A GeolocateControl control provides a button that uses the browser's geolocation API to locate the user on the map. Not all browsers support geolocation, and some users may disable the feature. Geolocation support for modern browsers including Chrome requires sites to be served over HTTPS. If geolocation support is not available, the GeolocateControl will not be visible. The zoom level applied will depend on the accuracy of the geolocation provided by the device. The GeolocateControl has two modes. If trackUserLocation is false (default) the control acts as a button, which when pressed will set the map's camera to target the user location. If the user moves, the map won't update. This is most suited for the desktop. If trackUserLocation is true, the control acts as a toggle button that when active the user's location is actively monitored for changes. In this mode the GeolocateControl has three states:

active - the map's camera automatically updates as the user's location changes, keeping the location dot in the center.
passive - the user's location dot automatically updates, but the map's camera does not.
disabled

Constructor

tt.GeolocateControl([options])

Example

map.addControl(new tt.GeolocateControl({
   positionOptions: {
       enableHighAccuracy: true
   },
   trackUserLocation: true
}));

Parameters

Name	Description
options Object default:None	Object with options
options.positionOptions Object default:{enableHighAccuracy:false,timeout:6000}	A Geolocation API PositionOptions object.
options.fitBoundsOptions Object default:{maxZoom:15}	A fitBounds options object to use when the map is panned and zoomed to the user's location. The default is to use a maxZoom of 15 to limit how far the map will zoom in for very accurate locations.
options.trackUserLocation Boolean default:false	If true the Geolocate Control becomes a toggle button and when active the map will receive updates to the user's location as it changes.
options.showAccuracyCircle Boolean default:true	By default, if showUserLocation is true, a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to false to disable. Always disabled when showUserLocation is false.
options.showUserLocation Boolean default:true	By default a dot will be shown on the map at the user's location. Set to false to disable.

Methods

off(type, listener): Object

Removes a previously registered event listener.

Parameters

Name	Description
type Required String default:None	The event type to remove listeners.
listener Required Function default:None	The listener function to remove.

Returns

Object this

on(type, listener): Object

Adds a listener to a specified event type.

Parameters

Name	Description
type Required String default:None	The event type to add a listen for.
listener Required Function default:None	The function to be called when the event is fired. The listener function is called with the data object passed to fire, extended with the target and type properties.

Returns

Object this

once(type, listener): Object

Adds a listener that will be called only once to a specified event type. The listener will be called the first time the event fires after the listener is registered.

Parameters

Name	Description
type Required String default:None	The event type to listen for.
listener Required Function default:None	The function to be called when the event is fired the first time.

Returns

Object this

trigger( ): Boolean

Trigger a geolocation

Returns

Boolean Returns false if called before control was added to a map, otherwise returns true.

Events

All the class events are keys of the Events static member.

To learn more about how to listen events please refer to the Evented class.

error : PositionError

Fired on each Geolocation API position update that returned as an error. It returns a PositionError object from the callback in Geolocation.getCurrentPosition() or Geolocation.watchPosition().

geolocate : Position

Fired on each Geolocation API position update which returned as success. It returns a Position object from the callback in Geolocation.getCurrentPosition() or Geolocation.watchPosition().

trackuserlocationend

Fired when the Geolocate Control changes to the background state, which happens when a user changes the camera during an active position lock. This only applies when trackUserLocation is true. In the background state, the dot on the map will update with location updates but the camera will not.

trackuserlocationstart

Fired when the Geolocate Control changes to the active lock state, which happens either upon first obtaining a successful Geolocation API position for the user (a geolocate event will follow), or the user clicks the geolocate button when in the background state which uses the last known position to recenter the map and enter active lock state (no geolocate event will follow unless the users's location changes).