Displaying an Interactive Map (v2.5)
Your app can use the Amazon Maps API to display a map that the user can pan, zoom, and tilt.By default, the map handles user interaction in response to touch input.
- Displaying the Map in a MapFragment
- Setting Initial Map Options
- Getting a Reference to the Map
- Moving and Zooming the Camera
Displaying the Map in a MapFragment
The simplest way to set up a map is to define it in the XML file that specifies your app's layout.You can include the map in a MapFragment
or SupportMapFragment
(for devices earlier than API 12).Then make sure your Activity
class references the layout.
MapView
.This is more complex because you must call lifecycle methods yourself.These methods are called automatically when using the MapFragment
or SupportMapFragment
classes.For example, the following XML defines a MapFragment
that can display an Amazon map.You can place this XML anywhere within your layout:
<fragment
android:id="@+id/mapFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
class="com.amazon.geo.mapsv2.MapFragment" />
Then, set your Activity
to display the fragment:
public class CoffeeActivity extends Activity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Set the activity to display the fragment defined in activity_my_main.xml.
setContentView(R.layout.activity_map_v2);
}
}
Alternatively, define the fragment or view in code:
...
private MapFragment mMapFragment;
private static final String MAP_FRAGMENT_TAG = "mapfragment";
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Set the activity to display the layout defined in programmatic_layout.xml.
setContentView(R.layout.programmatic_layout);
// Create a map fragment with default options
MapFragment mMapFragment = MapFragment.newInstance();
// Add the new fragment to the fragment manager.Note that
// fragment_container is the ID for the frame layout defined in
// programmatic_layout.xml
getFragmentManager().beginTransaction()
.add(R.id.fragment_container, mMapFragment, MAP_FRAGMENT_TAG).commit();
}
Setting Initial Map Options
You can define the initial settings for the map before displaying the map.For instance, you can set the map to initially display as a satellite rather than the normal base map.
The initial map settings you can use are defined as part of the AmazonMapOptions
class.How you set these depends on how you add your map to the app:
- When defining your
MapFragment
orMapView
in the layout XML, set the initial options in the XML with custom attributes. - When defining your
MapFragment
orMapView
in code, pass the preferred settings in anAmazonMapOptions
object.
Defining Initial Settings in XML
To define map settings in the layout XML:
-
Include the following XML namespace in the XML layout (note that the prefix can be any value; it does not need to be "map"):
xmlns:map="http://schemas.android.com/apk/res-auto"
-
Set your attributes.For example, use the
map:amzn_mapType
attribute to set the map type (normal or satellite).This example sets the map to satellite in the XML:
<fragment xmlns:android="http://schemas.android.com/apk/res/android" xmlns:map="http://schemas.android.com/apk/res-auto" android:id="@+id/map" android:layout_width="match_parent" android:layout_height="match_parent" map:amzn_mapType="amzn_satellite" class="com.amazon.geo.mapsv2.MapFragment"/>
See Maps API Reference for details on the XML attributes with the related AmazonMapOptions
methods.
Defining Initial Settings in Code
To define map settings in the code:
-
Create an
AmazonMapOptions
object with the settings you want. -
Pass the
AmazonMapOptions
object to theMapFragment.newInstance()
method.
This example sets the map to satellite in code:
// Create an AmazonMapOptions object to set the initial options on the map
AmazonMapOptions mapOpt = new AmazonMapOptions();
mapOpt.mapType(AmazonMap.MAP_TYPE_SATELLITE);
// Create a map fragment with options
MapFragment mMapFragment = MapFragment.newInstance(mapOpt);
Getting a Reference to the Map
AmazonMap
is the primary class you use to interact with the map.You cannot instantiate this class.You must retrieve a reference to it from the fragment or view object with the .getMapAsync()
method.Pass this method an object that implements the OnMapReadyCallback
interface.When the map object is ready to be used, it is provided to you as an argument to the onMapReady()
callback method.You can place your main map code within this method, or assign the object to a global variable to use elsewhere.
The AmazonMap
object provided in the callback is never null
, so you do not need to check it before using the object.Note that you must call .getMapAsync()
on the main thread as the callback is invoked on the main thread.
The following example displays the map in a MapFragment
with the ID mapFragment
:
private MapFragment mMapFragment;
...
// Extract a reference to the map fragment
mMapFragment = (MapFragment) getFragmentManager().findFragmentById(
R.id.mapFragment);
// Call .getMapAsync() and pass it an object that implements
// the OnMapReadyCallback interface.
mMapFragment.getMapAsync(new OnMapReadyCallback() {
@Override
public void onMapReady(AmazonMap amazonMap) {
// This method is called when the map is ready.The AmazonMap
// object provided to this method will never be null.
// Use the map reference to set UI settings and other options.
amazonMap.getUiSettings().setZoomControlsEnabled(true);
amazonMap.setTrafficEnabled(true);
}
});
Moving and Zooming the Camera
The map camera determines the area of the world shown by the map (latitude/longitude, zoom, bearing, and tilt).The current camera position is represented by a CameraPosition
object; you can retrieve this object from the AmazonMap
but cannot change the CameraPosition
directly.
To change the part of the world shown by the map, create a CameraUpdate
object representing the new position and pass it to one of the AmazonMap.moveCamera
or AmazonMap.animateCamera
methods.Use the methods in the CameraUpdateFactory
class to create the CameraUpdate
object; these methods let you specify which camera properties you want to change.
You can change any or all of the camera properties:
- Target — the latitude and longitude position at the center of the map.
-
Zoom level — the scale of the area shown.As the number becomes larger, the camera moves closer to the earth to show less area but with more detail.
Important: For existing projects, Maps API v2.5 generates slightly different views against the same zoom levels.Test your zoom level against the newer Maps API to ensure the best user experience. - Bearing — the orientation of the map.Bearing is measured in degrees and works similar to compass bearings.For example, setting bearing to 0 orients the map with North at the top, while setting the bearing to 270 rotates the map to position due West at the top.
- Tilt — the angle of the camera in relation to the earth, expressed in degrees.
For example, call CameraUpdateFactory.newLatLongZoom()
to create a CameraUpdate
that changes the camera latitude, longitude, and zoom level but leaves all other properties untouched:
// Define the latitude, longitude, and zoom level
private static final double COFFEE_LATITUDE = 47.624548;
private static final double COFFEE_LONGITUDE = -122.321006;
private static final LatLng COFFEE_LATLNG = new LatLng(COFFEE_LATITUDE, COFFEE_LONGITUDE);
private static final float COFFEE_ZOOM = 18.0F;
@Override
public void onMapReady(AmazonMap amazonMap) {
// Animate the camera to the specified location and zoom level
amazonMap.animateCamera(CameraUpdateFactory.newLatLngZoom(COFFEE_LATLNG, COFFEE_ZOOM));
...
}