Map Object

In logic, a Map is an object that can be used to display and control an interactive map. The map may be panned and zoomed with touch controls and may optionally show the user's current location. Using map functions you can add markers at geographic positions on the map, add custom buttons, and set the geographical area displayed. You can also specify user-defined functions in your logic to be called when the user taps on markers, buttons, and on the map itself. Together, these functions allow for rich map-based interactions such as showing households on a map and launching an interview when the user taps a household.

To display a map, call the Map.show function. The map will be displayed allowing the user to interact with it until the user taps the back button or the Map.hide function is called from program logic.

You can call map functions to add markers, buttons, set the base map, and pan/zoom before showing the map. This will be more efficient than adding them afterwards, especially when adding large numbers of markers. You can also call the map functions after showing the map from within any of the user-defined callback functions for map, marker, and button clicks and drags.

You can add markers to the map using the Map.addMarker function. You can replace the default marker icon with a custom image by calling Map.setMarkerImage or with a text icon using Map.setMarkerText.

By default, the map contains a button to zoom to the users current location. You can add additional buttons to the map by calling Map.addImageButton or Map.addTextButton.

You add vector geometry, such as polygons and polylines, to the map using the Map.addGeometry function.

By default, the map will display a base map from Google Maps, which requires an Internet connection. With no Internet connection the base map will be empty. To display a map without an Internet connection you can copy an offline map file to your device and pass the file to the Map.setBaseMap function.

Functionality

A Map is a CSPro logic object that allows the following functions to be called via dot notation:

Function	Description
show	Display the map and allow the user to interact with it.
hide	End displaying the map if it is currently showing.
clear	Reset the map's properties to the default state.

setTitle	Set the map title.
setBaseMap	Change the map source to an online or offline base map.
zoomTo	Pan/zoom the map.
showCurrentLocation	Display the current location (as retrieved from the GPS) on the map.
saveSnapshot	Save the currently-displayed map as an image.

setOnClick	Set the user-defined function that is called when the user taps on the map.
getLastClickLatitude	Retrieve the latitude of the last point on the map the user tapped.
getLastClickLongitude	Retrieve the longitude of the last point on the map the user tapped.

addMarker	Place a marker on the map at the specified latitude and longitude.
removeMarker	Delete a single marker from the map.
clearMarkers	Delete all markers from the map.
setMarkerImage	Set the icon displayed on the map for a specific marker.
setMarkerText	Set text displayed on the map for a specific marker.
setMarkerDescription	Set text displayed in a popup window when a specific marker is tapped.
setMarkerOnClick	Set the user-defined function that is called when the user taps a marker.
setMarkerOnClickInfoWindow	Set the user-defined function that is called when the user taps on a marker's popup info.
setMarkerOnDrag	Set the user-defined function that is called when the user a drags a marker on the map.
setMarkerLocation	Move an existing marker to a new position on the map.
getMarkerLatitude	Retrieve the latitude of a marker on the map.
getMarkerLongitude	Retrieve the longitude of a marker on the map.

addGeometry	Add vector geometry to the map.
removeGeometry	Delete vector geometry from the map.
clearGeometry	Delete all vector geometry from the map.

addTextButton	Create a button with a text label on the map.
addImageButton	Create a button with an icon on the map.
removeButton	Delete a button on the map.
clearButtons	Delete all buttons from the map.

getLabel	Returns the symbol's label.
getName	Returns the symbol's name.
getJson	Returns the symbol's metadata represented in JSON.

Assignments

When a Map object is used as an argument to a user-defined function, it is passed by reference.

Example

// Declare a map
Map mymap;

// Add a marker to the map at latitude 38.84839, longitude -76.931098
mymap.addMarker(38.84839, -76.931098);

// Display the map
mymap.show();