Basic Map Display

MapView

MapView is a crucial component of the Android Maps SDK that allows developers to display maps in their Android applications. With MapView, developers can create engaging and interactive location-based experiences for their users. This custom view provides a powerful set of features, including map styling, markers, camera animations, and user interactions such as touch and zoom. Whether you're building a mapping app, location-based service, or simply need to display maps in your application, MapView is the key to making it happen. The Android Maps SDK provides an easy-to-use and flexible API that makes it simple to integrate MapView into your app and start creating amazing maps experiences.

Integration of MapView

There are two ways to integrate a MapView to your App

1. Add MapView to your layout XML

   1
   <ai.nextbillion.maps.core.MapView
   2
   android:id="@+id/map_view"
   3
   android:layout_width="match_parent"
   4
   android:layout_height="match_parent" />
   5
   
   6
   
   7
   <ai.nextbillion.maps.core.MapView
   8
   android:id="@+id/map_view"
   9
   android:layout_width="match_parent"
   10
   android:layout_height="match_parent"
   11
   app:nbmap_cameraTargetLat="40.38532445"
   12
   app:nbmap_cameraTargetLng="-82.91441935"
   13
   app:nbmap_cameraZoom="10" />

   This code creates a MapView object with an ID of map_view and sets its width and height to match the parent view. In the second code snippet, additional attributes such as nbmap_cameraTargetLat, nbmap_cameraTargetLng, and nbmap_cameraZoom are added to set the initial camera position and zoom level for the MapView.

2. Instantiate a MapView and then add it to a parent view

   1
   mapView = new MapView(context);
   2
   
   3
   
   4
   parentView.addView(mapView);
   5
   //or
   6
   setContentView(mapView);
   7
   
   

   This code creates a new instance of MapView by calling the constructor with a context object. The MapView is then added to a parent view either by calling parentView.addView(mapView) or setContentView(mapView). The choice of which method to use depends on the specific use case and the desired parent view.

Obtain Maps Interface

NextbillionMap is the interface of the MapView, which allows developers to make changes to the MapView, for example, add a marker to the MapView.

To get an instance of the NextbillionMap, we need to register an OnMapReadyCallback to the MapView as soon as we get the reference to it. There are two ways to register the callback:

1. Implementing the OnMapReadyCallback interface within the class that requires the NextbillionMap instance.

   1
   public class YourClass implements OnMapReadyCallback 
   2
   
   3
   private NextbillionMap nextbillionMap;
   4
   ...
   5
   mapView.getMapAsync(this);
   6
   ...
   7
   
   8
   @Override
   9
   public void onMapReady(@NonNull NextbillionMap nextbillionMap) {
   10
       this.nextbillionMap = nextbillionMap;
   11
   }

2. Defining an anonymous OnMapReadyCallback class.

   1
   private  OnMapReadyCallback onMapReadyCallback = new OnMapReadyCallback() {
   2
       @Override
   3
       public void onMapReady(@NonNull NextbillionMap nextbillionMap) {
   4
           this.nextbillionMap = nextbillionMap;
   5
       }
   6
   };
   7
   
   8
   ...
   9
   mapView.getMapAsync(onMapReadyCallback);
   10
   ...

Once the map is ready, the onMapReady method will be triggered and the nextbillionMap instance variable will be set to the NextbillionMap that is passed as an argument to the method. Now, the code can make changes to the MapView using the nextbillionMap instance.

Lifecycle of MapView

Also, to avoid unexpected behaviors, don’t forget to bind MapView’s lifecycle to Activity

1
@Override
2
protected void onCreate(Bundle savedInstanceState) {
3
   super.onCreate(savedInstanceState);
4
   setContentView(R.layout.activity_main);
5

6
   mapView = findViewById(R.id.map_view);
7
   mapView.onCreate(savedInstanceState);
8
   mapView.getMapAsync(this);
9
}
10

11
///////////////////////////////////////////////////////////////////////////
12
/// Lifecycle
13
////////////////////////////////////////////////////////////////////////
14

15
@Override
16
protected void onStart() {
17
   super.onStart();
18
   mapView.onStart();
19
}
20

21
@Override
22
protected void onResume() {
23
   super.onResume();
24
   mapView.onResume();
25
}
26

27
@Override
28
protected void onPause() {
29
   super.onPause();
30
   mapView.onPause();
31
}
32

33
@Override
34
protected void onStop() {
35
   super.onStop();
36
   mapView.onStop();
37
}
38

39
@Override
40
protected void onSaveInstanceState(@NonNull Bundle outState) {
41
   super.onSaveInstanceState(outState);
42
   mapView.onSaveInstanceState(outState);
43
}
44

45
@Override
46
protected void onDestroy() {
47
   super.onDestroy();
48
   mapView.onDestroy();
49
}
50

51
@Override
52
public void onLowMemory() {
53
   super.onLowMemory();
54
   mapView.onLowMemory();
55
}

The MapView's lifecycle should be bound to the activity's lifecycle by calling corresponding lifecycle methods of the MapView in each activity method, such as onCreate, onStart, onResume, onPause, onStop, onSaveInstanceState, onDestroy, and onLowMemory. In the onCreate method, the MapView is initialized with mapView.onCreate and loaded with mapView.getMapAsync. If you're using a fragment, call mapView.onDestroy() inside the fragment's onDestroyView().

Camera

The Android Maps SDK provides a camera component that allows developers to control the view of the map. The camera component can be used to manipulate the position, orientation, and zoom level of the map view. With the camera, developers can provide a customized map experience for their users, for example, by zooming in on specific locations or tilting the view to show a particular perspective. The camera component is essential in creating dynamic and interactive map-based applications with the Nextbillion Android Maps SDK.

Get current Camera Position

The code snippet demonstrates how to retrieve the current camera position from a NextbillionMap object.

1
 CameraPosition currentCameraPosition = nextbillionMap.getCameraPosition();
2
 double currentZoom = currentCameraPosition.zoom;
3
 double currentTilt = currentCameraPosition.tilt;

The getCameraPosition method of the NextbillionMap object is used to retrieve the current camera position, which is represented by a CameraPosition object. The CameraPosition object contains several properties, including the zoom level and the tilt angle of the camera. In this example, two variables are defined: currentZoom and currentTilt. These variables are set to the zoom and tilt properties of the CameraPosition object, respectively. This code will allow a developer to retrieve the current camera position and use it in further operations, such as adjusting the camera position or performing calculations based on the current camera position.

Update Camera Position

The code snippet demonstrates how to update the camera position in the NextbillionMap object.

1
int millisecondSpeed = 300;
2
CameraPosition position = new CameraPosition.Builder()
3
         .target(new LatLng(12.97551913,77.58917229))
4
         .zoom(12)
5
         .tilt(20)
6
         .build();
7
nextbillionMap.animateCamera(CameraUpdateFactory.newCameraPosition(position), millisecondSpeed);

The animateCamera method of the NextbillionMap is used to animate the camera to a new position, represented by a CameraPosition object.

A CameraPosition object is constructed using the CameraPosition.Builder class. The target position, zoom level, and tilt angle of the camera are specified using the target, zoom, and tilt methods, respectively. When a CameraPosition object is constructed, the CameraUpdate object is created using the CameraUpdateFactory.newCameraPosition method, passing the CameraPosition object as an argument.

Finally, the animateCamera method is called on the NextbillionMap object, passing the CameraUpdate object and the millisecondSpeed variable as arguments. The millisecondSpeed variable represents the speed of the camera animation, in milliseconds. The animateCamera method will animate the camera to the specified position over the specified duration, resulting in a smooth transition to the new camera position.

Annotations

For more details of annotations, please refer to Markers and Annotations.

Add a marker

The addMarker method takes an instance of the LatLng class as an argument, which represents the coordinates(latitude and longitude) of the marker. In this example, the marker is placed at the coordinate 12.97551913, 77.58917229. This line of code will add a marker to the map at that location, allowing the user to visualize and interact with the location in the map view.

1
nextbillionMap.addMarker(new LatLng(12.97551913,77.58917229));

Add a polyline

The addPolyline method takes three arguments: origin, dest, and a color value represented in an ARGB int. The origin and dest parameters represent the starting and ending points of the polyline respectively. The color value determines the color of the polyline.

In this example, the polyline is drawn from origin to dest and is set to the color with an ARGB value of 0xff00ffff, which represents a shade of cyan. This line of code will add a polyline to the map that connects the two points, allowing the user to visualize a path or route between them.

1
nextbillionMap.addPolyline(origin, dest, 0xff00ffff);

Add a polygon

The addPolygon method takes two arguments: a list of points and a color value represented in an ARGB int. The points parameter represents the vertices of the polygon. The color value determines the color of the polygon.

In this example, the polygon is defined by the vertices in points and is set to the color with an ARGB value of 0xffff0000, which represents the color red. This line of code will add a polygon to the map, allowing the user to visualize and interact with a region defined by the vertices.

1
nextbillionMap.addPolygon(points, 0xffff0000);