Modules.Map.View

Map view is used for embedding native mapping capabilities as a view in your application.

With native maps, you can control the mapping location, the type of map, the zoom level and you can add custom annotations and routes directly to the map. Once the map view is displayed, the user can pan, zoom and tilt the map using the native control gestures.

Use the Modules.Map.createView method to create a map view.

In Alloy, use the <Module> element with the module attribute set to ti.map and method attribute set to createView to create a map view in XML markup:

<Module module="ti.map" method="createView" />

All latitude and longitude values are specified in decimal degrees. Values in degrees, minutes and seconds (DMS) must be converted to decimal degrees before being passed to the map view.

You can add Annotation objects to the map to mark points of interest. An annotation has two states: selected and deselected. A deselected annotation is marked by a pin image. When selected, the full annotation is displayed, typically including a title and an optional subtitle.

You can add Route objects to the map to create paths between two or more points of interest.

To use the userLocation property in iOS 8 and later, add either the NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription key to the iOS plist section of the project's tiapp.xml file.

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationAlwaysUsageDescription</key>
                <string>
                    Specify the reason for accessing the user's location information.
                    This appears in the alert dialog when asking the user for permission to
                    access their location.
                </string>
            </dict>
        </plist>
    </ios>
</ti:app>

Extends: Titanium.UI.View · Since: 3.1.0, 3.2.0, 3.2.0, 9.2.0 · Platforms: android, iphone, ipad, macos

Properties #

animate#

Type: Boolean

Indicates if changes to the mapping region should be animated.

Setting this to 'false' will not stop the animation from clicking the My Location button,
since that is native Android behavior.

annotations#

Type: Array<Modules.Map.Annotation>

An array of annotations to add to the map.

There is no guarantee that the order of elements in the annotations property will be
maintained when creating, adding or deleting annotations from the Ti.Map.View object.
If the application depends on the annotations being in a set order, it should keep
references to all of the annotations in a separate array.

camera#

Type: Modules.Map.Camera

The camera used for determining the appearance of the map.

A camera object defines a point above the map's surface from which to view the map. Applying a camera to a map has the
effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so that it is oriented to match
the user's heading or to apply a pitch angle to tilt the plane of the map.

Assigning a new camera to this property updates the map immediately and without animating the change. If you want to
animate changes in camera position, use the animateCamera method instead.

You must not set this property to null. To restore the map to a flat appearance, apply a camera with a pitch angle of 0,
which yields a camera looking straight down onto the map surface.

compassEnabled#

Type: Boolean

Enable or disables the compass button.

enableZoomControls#

Type: Boolean

Enables or disables the built-in zoom controls.

If enabled, the zoom controls are a pair of buttons (one for zooming in, one for zooming out) that appear on the screen.
When pressed, they cause the camera to zoom in (or out) by one zoom level. If disabled, the zoom controls are not shown.

indoorEnabled#

Type: Boolean

A Boolean value indicating whether the indoor mapping is enabled.

This property is used to enabled/disable the indoor mapping feature of Google Maps.
Changing the value after the MapView is drawn can cause flickering.
You can read more at:
Google Indoor Maps

liteMode#

creation only

Type: Boolean

Create a liteMode map version

When the liteMode is switched on the map will be displayed as a bitmap with limited interaction.
Please refer to Google developers documentation
for more details.

mapToolbarEnabled#

Type: Boolean

Enable or disables the map toolbar.

mapType#

Type: Number

Map type constant, either Modules.Map.NORMAL_TYPE, Modules.Map.SATELLITE_TYPE,
Modules.Map.TERRAIN_TYPE, Modules.Map.HYBRID_TYPE, Modules.Map.HYBRID_FLYOVER_TYPE or
Modules.Map.SATELLITE_FLYOVER_TYPE.

maxZoomLevel#

Type: Number

Returns the maximum zoom level available at the current camera position.

Returns the maximum zoom level for the current camera position.
This takes into account what map type is currently being used.
For example, satellite or terrain may have a lower max zoom level than the base map tiles.

This will only give the correct value after the 'complete' event is fired.

minClusterSize#

Type: Number

Sets the minium size of a cluster.

The minium cluster size is the smallest number of annotations that are merged together and
(minClusterSize + 1) is the smallest number that will appear on the cluster.

minZoomLevel#

Type: Number

Returns the minimum zoom level available at the current camera position.

Returns the minimum zoom level. This is the same for every location (unlike the maximum zoom level)
but may vary between devices and map sizes.

This will only give the correct value after the 'complete' event is fired.

padding#

Type: MapViewPadding

Sets the distance between each edges of the view to the map controls.

The map view controls may be obscured by other elements.

pitchEnabled#

Type: Boolean

A Boolean value indicating whether the map camera's pitch information is used.

When this property is set to true and a valid camera is associated with the map,
the camera's pitch angle is used to tilt the plane of the map. When this property
is set to false, the camera's pitch angle is ignored and the map is always displayed
as if the user is looking straight down onto it.

region#

Type: MapRegionTypev2

A dictionary specifying the location and zoom level of the map.

rotateEnabled#

Type: Boolean

A Boolean value indicating whether the map camera's heading information is used.

When this property is set to true and a valid camera is associated with the map,
the camera's heading angle is used to rotate the plane of the map around its center
point. When this property is set to false, the camera's heading angle is ignored and the
map is always oriented so that true north is situated at the top of the map view.

scrollEnabled#

Type: Boolean

A Boolean value indicating whether the map can be scrolled by dragging gesture.

When this property is set to true the a map view can be panned or scrolled by dragging the map view.

showsBuildings#

Type: Boolean

A Boolean indicating whether the map displays extruded building information.

When this property is set to true and the camera has a pitch angle greater than zero,
the map extrudes buildings so that they extend above the map plane, creating a 3D effect.
The mapType property must be set to Modules.Map.NORMAL_TYPE for extruded buildings to be displayed.

showsCompass (deprecated)#

Type: Boolean

A Boolean indicating whether the map displays a compass control.

When this property is set to true, the map displays the control that lets users change the heading
orientation of the map.

showsPointsOfInterest#

Type: Boolean

A Boolean indicating whether the map displays point-of-interest information.

When this property is set to true, the map displays icons and labels for restaurants,
schools, and other relevant points of interest.

showsScale#

Type: Boolean

A Boolean indicating whether the map shows scale information.

When this property is set to true, the map displays the scale information.

showsTraffic#

Type: Boolean

A Boolean value indicating whether the map displays traffic information.

The mapType property must be set to Modules.Map.NORMAL_TYPE or Modules.Map.HYBRID_TYPE for
traffic information to be shown.

style#

Type: String

JSON String to style the Map.

This property will change the look (colors, roads, labels) of the map. A valid JSON can be created
at Google Maps Styling Wizard

traffic#

Type: Boolean

Toggles the traffic layer on or off.

Set to true to display the traffic layer or false to hide it.
This is subject to the availability of traffic data.

userLocation#

Type: Boolean

Boolean indicating if the user's current device location should be shown on the
map.

If true, the user's location is marked with a pin, and the My Location button will appear in the top
right corner of the screen. Starting in iOS 8, permissions must be added to tiapp.xml. Details in description.

userLocationButton#

Type: Boolean

Enable or disables the My Location button. If the button is enabled, it is only shown when userLocation
is enabled.

If true, the My Location button is enabled.

zoom#

Type: Number

Returns the current zoom level from the current camera position.

Returns the current zoom level from the current camera position.
Note: This will only return the correct value once the complete event is fired.

zoomEnabled#

Type: Boolean

A Boolean value indicating whether the map can be zoomed by pinching or tapping.

When this property is set to true the a map view can be zoomed by pinching inwards to zoom out
and reverse to zoom in. Zooming in can also be accomplished by double-tapping the map view. Zooming
out can also be accomplished by two-finger tapping the map view.

zOrderOnTop#

creation only

Type: Boolean

Controls wether the map view's surface is placed on top of its window.

Please refer to zOrderOnTop
for more details.

Methods #

addAnnotation #

Adds a new annotation to the map.

Parameters:

Name	Type	Summary	Optional
`annotation`	`Modules.Map.Annotation`	a Modules.Map.Annotation instance.	No

addAnnotations #

Adds one or more new annotations to the map.

Parameters:

Name	Type	Summary	Optional
`annotations`	`Array<Modules.Map.Annotation>`	Array of Annotation objects	No

addCircle #

Adds a new circle to the map.

Parameters:

Name	Type	Summary	Optional
`circle`	`Modules.Map.Circle`	a Modules.Map.Circle instance.	No

addCircles #

Adds one or more new circles to the map.

Parameters:

Name	Type	Summary	Optional
`circles`	`Array<Modules.Map.Circle>`	Array of Circle objects	No

addHeatmap #

Adds a heatmap to the map.

A heatmap is defined by an array of coordinates.

Parameters:

Name	Type	Summary	Optional
`coordinates`	`MapPointType`	An array of coordinates	No

addImageOverlay #

Adds a new image overlay to the map.

Parameters:

Name	Type	Summary	Optional
`imageOverlay`	`Modules.Map.ImageOverlay`	A Modules.Map.ImageOverlay instance.	No

addImageOverlays #

Adds one or more new image overlays to the map.

Parameters:

Name	Type	Summary	Optional
`imageOverlays`	`Array<Modules.Map.ImageOverlay>`	Array of ImageOverlay objects	No

addPolygon #

Adds a new polygon to the map.

Parameters:

Name	Type	Summary	Optional
`polygon`	`Modules.Map.Polygon`	a Modules.Map.Polygon instance.	No

addPolygons #

Adds one or more new polygons to the map.

Parameters:

Name	Type	Summary	Optional
`polygons`	`Array<Modules.Map.Polygon>`	Array of Polygons objects	No

addPolyline #

Adds a new polylines to the map.

Parameters:

Name	Type	Summary	Optional
`polygon`	`Modules.Map.Polyline`	a Modules.Map.Polyline instance.	No

addPolylines #

Adds one or more new polylines to the map.

Parameters:

Name	Type	Summary	Optional
`polylines`	`Array<Modules.Map.Polyline>`	Array of Polyline objects	No

addRoute #

Adds a route to the map.

Parameters:

Name	Type	Summary	Optional
`route`	`Modules.Map.Route`	Modules.Map.Route	No

animateCamera #

Changes the camera used for determining the map's viewing parameters and animates the change.

Parameters:

Name	Type	Summary	Optional
`animationParams`	`CameraAnimationParams`	Properties for controlling the camera animation. The property `camera` is required.	No
`callback`	`Callback<Object>`	A method that will be called when the camera animation completes. Optionally, the completion of camera animations can be captured by listening for a `regionchanged` event with `animated` set to true.	No

containsCoordinate #

Validated whether or not a given coordinate is currently visible
in the map rect.

Parameters:

Name	Type	Summary	Optional
`coordinate`	`MapPointType`	The `latitude` and `longitude` pair represented by an Object.	No

Returns: Boolean — Returns `true` if given coordinate is within the displayed map view.

deselectAnnotation #

Deselects the specified annotation, so the main annotation is hidden and only
a pin image is shown.

Parameters:

Name	Type	Summary	Optional
`annotation`	`String, Modules.Map.Annotation`	Annotation to deselect, identified by an annotation title or a Modules.Map.Annotation reference.	No

removeAllAnnotations #

Removes all annotations from the map.

removeAllCircles #

Remove all circles from the map.

removeAllImageOverlays #

Remove all image overlays from the map.

removeAllPolygons #

Remove all polygons from the map.

removeAllPolylines #

Remove all polylines from the map.

removeAnnotation #

Removes an existing annotation from the map.

Parameters:

Name	Type	Summary	Optional
`annotation`	`String, Modules.Map.Annotation`	Annotation to remove, identified by an annotation title or a Modules.Map.Annotation reference.	No

removeAnnotations #

Removes one or more existing annotations from the map.

Annotations can be identified by title or by a Modules.Map.Annotation
reference.

Parameters:

Name	Type	Summary	Optional
`annotations`	`Array<String>, Array<Modules.Map.Annotation>`	Array of annotations to remove.	No

removeCircle #

Remove a circle from the map.

Parameters:

Name	Type	Summary	Optional
`circle`	`Modules.Map.Circle`	An Circle object	No

removeImageOverlay #

Remove an image overlay from the map.

Parameters:

Name	Type	Summary	Optional
`imageOverlay`	`Modules.Map.ImageOverlay`	An ImageOverlay object	No

removePolygon #

Remove a polygon from the map.

Parameters:

Name	Type	Summary	Optional
`polygon`	`Modules.Map.Polygon`	A Polygon object	No

removePolyline #

Remove a polyline from the map.

Parameters:

Name	Type	Summary	Optional
`polyline`	`Modules.Map.Polyline`	An Polyline object	No

removeRoute #

Remove a previously added route.

Parameters:

Name	Type	Summary	Optional
`route`	`Modules.Map.Route`	An instance of Modules.Map.Route	No

selectAnnotation #

Selects the annotation, showing the full annotation.

Parameters:

Name	Type	Summary	Optional
`annotation`	`String, Modules.Map.Annotation`	Annotation to show, identified by an annotation title or a Modules.Map.Annotation reference.	No

setClusterAnnotation #

Set new cluster annotation for the clustered annotation.

This method should be called inside the clusterstart event.
See the example "Map Example With Marker Annotation and Clustering".

Parameters:

Name	Type	Summary	Optional
`clusterAnnotationParam`	`ClusterAnnotationParams`	Properties for creating cluster annotation.	No

setLocation #

Sets the map location and zoom level.

The location is set using a simple dictionary object, described in <MapLocationTypeV2>. If latitudeDelta
and longitudeDelta are set, these specified parameters bound the area of interest, which is centered
and displayed at the greatest possible zoom level. This method can only be called after the map
completes loading. Before that, use region to set the map location.
For example:

myMapView.setLocation({
  latitude: 37.337681,
  longitude: -122.038193,
  animate: true,
  latitudeDelta: 0.04,
  longitudeDelta: 0.04
});

Parameters:

Name	Type	Summary	Optional
`location`	`MapLocationTypeV2`	Dictionary specifying the location and the zoom level for the map.	No

setMapType #

Sets the type of map (satellite, normal, or terrain).

Parameters:

Name	Type	Summary	Optional
`mapType`	`Number`	Map type constant, either Modules.Map.NORMAL_TYPE, Modules.Map.SATELLITE_TYPE, Modules.Map.TERRAIN_TYPE, Modules.Map.HYBRID_TYPE, Modules.Map.HYBRID_FLYOVER_TYPE or Modules.Map.SATELLITE_FLYOVER_TYPE.	No

showAnnotations #

Sets the visible region so that the map displays the specified annotations. If no array is passed
annotations on the map will be shown. The default padding of 20px is applied and can be changed by
using the Modules.Map.View.padding property.

Parameters:

Name	Type	Summary	Optional
`annotations`	`Array<Modules.Map.Annotation>`	An array of Modules.Map.Annotation to display.	Yes

snapshot #

Takes a snapshot of the map

Takes a snapshot of the current map and returns the image via onsnapshotready event.

zoom #

Zooms in or out of the map.

Zooms in or out by specifying a relative zoom level. A positive value increases
the current zoom level and a negative value decreases the zoom level.

Each increase in zoom level increases the magnification by a factor of two.

Parameters:

Name	Type	Summary	Optional
`level`	`Number`	Relative zoom level (positive to zoom in, negative to zoom out).	No

Events #

click #

Fired when the user selects or deselects an annotation, a polygon, a polyline or a circle.

Note that the click event is not fired every time the user clicks on the map.
It is fired in two circumstances:

The user clicks on the annotation. This will select the annotation.
The user deselects an annotation either by clicking on the map or another annotation.
The user clicks on a polygon, a polyline or a circle.

Note that only one annotation can be selected at any given time.

The click event includes a value, clicksource, which describes the part of the annotation
that was clicked. The clicksource can be one of pin, infoWindow, leftButton or rightButton
on iOS and pin, title, subtitle, leftPane, rightPane, infoWindow or null on Android.
If the user deselects an annotation by clicking on the pin, clicksource is pin.
If the user deselects the annotation by clicking elsewhere in the map view, clicksource is map.

For polygon, polyline or circle, The click event includes the following values.
clicksource is a string describing the shape type. map is the map view instance.
latitude and longitude is the corresponding coordinates on the map where the user
clicked in the shape.

Event Properties:

Name	Type	Summary
`title`	`String`	Title of the annotation.
`subtitle`	`String`	Subtitle of the annotation.
`map`	`Modules.Map.View`	The map view instance.
`clicksource`	`String`	Source of the click event. Can be one of `pin`, `leftPane`, `rightPane`, `infoWindow` or `null`. If it's a shape, it can be one of `polygon`, `polyline`, or `circle`. On Android, this also applies for `title` and `subtitle`.
`annotation`	`Modules.Map.Annotation`	Annotation source object.
`latitude`	`Number`	Latitude of the clicked annotation or the point clicked in the polygon, polyline and circle.
`longitude`	`Number`	Longitude of the clicked annotation or the point clicked in the polygon, polyline and circle.
`deselected`	`Boolean`	Will show if the annotation was selected (false) or deselected (true)

clusterstart #

Fired when a collision between annotations occurs.

Event Properties:

Name	Type	Summary
`memberAnnotations`	`Array<Modules.Map.Annotation>`	Array of annotations participating in clustering.
`map`	`Modules.Map.View`	This map view.

complete #

Fired when the map completes loading.

longclick #

Fired when the user makes a long-press gesture on the map.

A long press is generated by touching and holding on the touch screen.

The event occurs before the finger/button is lifted.

The longclick event returns longitude and latitude of the point on the ground that was pressed.

Event Properties:

Name	Type	Summary
`latitude`	`Number`	latitude of the point on the ground that was pressed.
`longitude`	`Number`	longitude of the point on the ground that was pressed.
`map`	`Modules.Map.View`	The map view instance.

mapclick #

Fired when the user clicks on the map

The mapclick event is fired when the user clicks on the map and returns the longitude/latitude of
that position.

Event Properties:

Name	Type	Summary
`map`	`Modules.Map.View`	The map view instance.
`latitude`	`Number`	Latitude of the clicked position.
`longitude`	`Number`	Longitude of the clicked position.

onsnapshotready #

Fired when the snapshot is ready after snapshot is invoked.

Event Properties:

Name	Type	Summary
`snapshot`	`Titanium.Blob`	snapshot of the current map

pinchangedragstate #

Fired when the user interacts with a draggable annotation.

Event Properties:

Name	Type	Summary
`annotation`	`Modules.Map.Annotation`	Annotation being dragged.
`map`	`Modules.Map.View`	This map view.
`title`	`String`	Annotation title.
`newState`	`Number`	New drag state for the annotation, one of ANNOTATION_DRAG_STATE_NONE, ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_DRAG, ANNOTATION_DRAG_STATE_CANCEL or ANNOTATION_DRAG_STATE_END.
`oldState`	`Number`	Previous drag state for the annotation, one of ANNOTATION_DRAG_STATE_NONE, ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_DRAG, ANNOTATION_DRAG_STATE_CANCEL or ANNOTATION_DRAG_STATE_END.

poiclick #

Fired when the user selects a Point of Interest (e.g. restaurant or hotel).

Make sure to use the Modules.Map.View.selectableMapFeatures property to define
annotations tha should be selectable. Available in iOS 16+

Event Properties:

Name	Type	Summary
`name`	`String`	The descriptive name associated with the map item.
`featureType`	`Number`	The type of map feature this annotation represents. See the Apple docs for all possible enum values.
`pointOfInterestCategory`	`Number`	The point-of-interest category for the map item. See the Apple docs for all possible enum values.
`phoneNumber`	`String`	The phone number associated with a business at the specified location.
`url`	`String`	The URL associated with the specified location.
`place`	`Object`	The placemark object containing the location information.
`latitude`	`Number`	Latitude of the annotation that was selected.
`longitude`	`Number`	Longitude of the annotation that was selected.

poideselect #

Fired when the user deselects a Point of Interest (e.g. restaurant or hotel).

regionchanged #

Fired when the mapping region finished changing.

Event Properties:

Name	Type	Summary
`longitude`	`Number`	Longitude value for the center point of the map, in decimal degrees.
`latitude`	`Number`	Latitude value for the center point of the map, in decimal degrees.
`longitudeDelta`	`Number`	The amount of east-to-west distance displayed on the map, measured in decimal degrees.
`latitudeDelta`	`Number`	The amount of north-to-south distance displayed on the map, measured in decimal degrees.
`animated`	`Boolean`	The regionchanged event was caused by an `animation`, such as a animating the camera.

regionwillchange #

Fired when the mapping region will change.

Event Properties:

Name	Type	Summary
`longitude`	`Number`	Longitude value for the center point of the map, in decimal degrees.
`latitude`	`Number`	Latitude value for the center point of the map, in decimal degrees.
`longitudeDelta`	`Number`	The amount of east-to-west distance displayed on the map, measured in decimal degrees.
`latitudeDelta`	`Number`	The amount of north-to-south distance displayed on the map, measured in decimal degrees.
`animated`	`Boolean`	The regionwillchange event was caused by an `animation`, such as a animating the camera.
`reason`	`Number`	The reason for the camera change, either Modules.Map.REASON_API_ANIMATION, Modules.Map.REASON_DEVELOPER_ANIMATION or Modules.Map.REASON_GESTURE.

userLocation #

Fired when the user changes on the map.

When the user location is available or changes at the map it will fire the event.

Event Properties:

Name	Type	Summary
`latitude`	`Number`	Latitude of the point on the ground that was pressed.
`longitude`	`Number`	Longitude of the point on the ground that was pressed.

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Modules.Map.View ​

Properties #

animate#

annotations#

camera#

compassEnabled#

enableZoomControls#

indoorEnabled#

liteMode#

mapToolbarEnabled#

mapType#

maxZoomLevel#

minClusterSize#

minZoomLevel#

padding#

pitchEnabled#

region#

rotateEnabled#

scrollEnabled#

showsBuildings#

showsCompass (deprecated)#

showsPointsOfInterest#

showsScale#

showsTraffic#

style#

traffic#

userLocation#

userLocationButton#

zoom#

zoomEnabled#

zOrderOnTop#

Methods #

addAnnotation #

addAnnotations #

addCircle #

addCircles #

Modules.Map.View