Merge pull request #63 from heremaps/esd/978

ESD-978: Update example apps for release 4.6.3.0

Author: datasun

README.md

@@ -54,6 +54,7 @@
 import java.util.List;
 import java.util.Locale;
 
+// Provides UI elements for indoor route calculation and displays an indoor route on the map.
 public class IndoorRoutingUIController implements LongPressListener {
     private static final String TAG = IndoorRoutingUIController.class.getSimpleName();
     private VenueMap venueMap;
@@ -83,9 +84,15 @@ public IndoorRoutingUIController(
         this.venueMap = venueEngine.getVenueMap();
         this.mapView = mapView;
         context = indoorRoutingLayout.getContext();
-        mapView.getGestures().setLongPressListener(this);
+
+        // Initialize IndoorRoutingEngine to be able to calculate indoor routes.
         engine = new IndoorRoutingEngine(venueEngine.getVenueService());
+        // Initialize IndoorRoutingController to be able to display indoor routes on the map.
         controller = new IndoorRoutingController(venueMap, mapView.getMapScene());
+        // Set a long press listener.
+        mapView.getGestures().setLongPressListener(this);
+
+        // Get end setup needed UI elements.
         this.indoorRoutingLayout = indoorRoutingLayout;
         indoorRoutingButton.setOnClickListener(v -> setVisible(!visible));
         indoorRoutingSettings = indoorRoutingLayout.findViewById(R.id.indoorRouteSettingsLayout);
@@ -120,22 +127,35 @@ public IndoorRoutingUIController(
                     .setOnClickListener(this ::onAvoidFeatureChanged);
         }
 
+        // Hide UI elements for indoor routes calculation.
         setVisible(false);
+        // Hide UI elements for indoor route settings.
         setSettingsVisible(false);
+        // Setup IndoorRouteStyle object.
         setUpRouteStyle();
     }
 
+    // Get visibility of UI elements for indoor routes calculation.
     public boolean isVisible() {
         return visible;
     }
 
+    // Setup IndoorRouteStyle object, which will be used in indoor route rendering.
     private void setUpRouteStyle() {
+        // Set start, end, walk and drive markers. The start marker will be shown at the start of
+        // the route and the destination marker at the destination of the route. The walk marker
+        // will be shown when the route switches from drive to walk mode and the drive marker
+        // vice versa.
         Anchor2D middleBottomAnchor = new Anchor2D(0.5, 1.0);
         routeStyle.setStartMarker(initMapMarker(R.drawable.ic_route_start, middleBottomAnchor));
         routeStyle.setDestinationMarker(initMapMarker(R.drawable.ic_route_end, middleBottomAnchor));
         routeStyle.setWalkMarker(initMapMarker(R.drawable.indoor_walk));
         routeStyle.setDriveMarker(initMapMarker(R.drawable.indoor_drive));
 
+        // Set markers for some of the indoor features. The 'up' marker indicates that the route
+        // is going up, and the 'down' marker indicates that the route is going down. The default
+        // marker indicates that a user should exit the current indoor feature (e.g. an elevator)
+        // to enter the current floor.
         IndoorFeatures[] features = new IndoorFeatures[] {IndoorFeatures.ELEVATOR,
                                                           IndoorFeatures.ESCALATOR,
                                                           IndoorFeatures.STAIRS,
@@ -148,6 +168,7 @@ private void setUpRouteStyle() {
         }
     }
 
+    // Creates a marker with a resource ID of an image and an anchor.
     private @Nullable MapMarker initMapMarker(final int resourceID, final Anchor2D anchor) {
         if (resourceID == 0) {
             return null;
@@ -160,6 +181,9 @@ private void setUpRouteStyle() {
         return null;
     }
 
+    // Gets a resource ID of an image based on the indoor feature and delta Z, where 0 means
+    // a standard icon, 1 means that the icon shows that route is going up, and -1 that it is
+    // going down.
     private int getIndoorFeatureResource(IndoorFeatures feature, int delta_z) {
         switch (feature) {
         case ELEVATOR:
@@ -214,6 +238,7 @@ private int getIndoorFeatureResource(IndoorFeatures feature, int delta_z) {
         return initMapMarker(resourceID, new Anchor2D());
     }
 
+    // Set visibility of UI elements for indoor routes calculation.
     private void setVisible(final boolean value) {
         if (visible == value) {
             return;
@@ -222,6 +247,7 @@ private void setVisible(final boolean value) {
         indoorRoutingLayout.setVisibility(visible ? View.VISIBLE : View.GONE);
     }
 
+    // Set visibility of UI elements for indoor routes settings.
     private void setSettingsVisible(final boolean value) {
         if (settingsVisible == value) {
             return;
@@ -230,31 +256,39 @@ private void setSettingsVisible(final boolean value) {
         indoorRoutingSettings.setVisibility(settingsVisible ? View.VISIBLE : View.GONE);
     }
 
+    // Create an indoor waypoint based on the tap point on the map.
     private @Nullable IndoorWaypoint getIndoorWaypoint(@NonNull final Point2D origin) {
         GeoCoordinates position = mapView.viewToGeoCoordinates(origin);
         if (position != null) {
+            // Check if there is a venue in the tap position.
             Venue venue = venueMap.getVenue(position);
             if (venue != null) {
                 VenueModel venueModel = venue.getVenueModel();
                 Venue selectedVenue = venueMap.getSelectedVenue();
                 if (selectedVenue != null &&
                     venueModel.getId() == selectedVenue.getVenueModel().getId()) {
+                    // If the venue is the selected one, return an indoor waypoint
+                    // with indoor information.
                     return new IndoorWaypoint(
                             position,
                             String.valueOf(venueModel.getId()),
                             String.valueOf(venue.getSelectedLevel().getId()));
                 } else {
+                    // If the venue is not the selected one, select it.
                     venueMap.setSelectedVenue(venue);
                     return null;
                 }
             }
 
+            // If the tap position is outside of any venue, return an indoor waypoint with
+            // outdoor information.
             return new IndoorWaypoint(position);
         }
 
         return null;
     }
 
+    // Update the text view with a new indoor waypoint.
     private void updateWaypointTextView(final TextView textView, final IndoorWaypoint waypoint) {
         StringBuilder text = new StringBuilder();
         if (waypoint.getVenueId() != null && waypoint.getLevelId() != null) {
@@ -273,43 +307,54 @@ private void updateWaypointTextView(final TextView textView, final IndoorWaypoin
         textView.setText(text.toString());
     }
 
-    public void onTap(@NonNull final Point2D origin) {
-        IndoorWaypoint waypoint = getIndoorWaypoint(origin);
-        if (visible && waypoint != null) {
-            destinationWaypoint = waypoint;
-            updateWaypointTextView(destinationTextView, waypoint);
-        }
-    }
-
+    // Handle the long press events.
     @Override
     public void onLongPress(@NonNull final GestureState state, @NonNull final Point2D origin) {
         if (!visible || state != GestureState.END) {
             return;
         }
         IndoorWaypoint waypoint = getIndoorWaypoint(origin);
         if (waypoint != null) {
+            // Set a start waypoint.
             startWaypoint = waypoint;
             updateWaypointTextView(startTextView, waypoint);
         }
     }
 
+    // Handle the tap events.
+    public void onTap(@NonNull final Point2D origin) {
+        IndoorWaypoint waypoint = getIndoorWaypoint(origin);
+        if (visible && waypoint != null) {
+            // Set a destination waypoint.
+            destinationWaypoint = waypoint;
+            updateWaypointTextView(destinationTextView, waypoint);
+        }
+    }
+
+    // Calculate an indoor route based on the start and destination waypoints, and
+    // the indoor route options.
     private void calculateRoute() {
         engine.calculateRoute(startWaypoint, destinationWaypoint, routeOptions, this ::showRoute);
     }
 
+    // Show the resulting route.
     private void showRoute(
             @Nullable final RoutingError routingError, @Nullable final List<Route> routeList) {
+        // Hide the existing route, if any.
         controller.hideRoute();
         if (routingError == null && routeList != null) {
             Route route = routeList.get(0);
+            // Show the resulting route with predefined indoor routing styles.
             controller.showRoute(route, routeStyle);
         } else {
+            // Show a toast message in case of error.
             Toast toast = Toast.makeText(
                     context, "Failed to calculate the indoor route!", Toast.LENGTH_LONG);
             toast.show();
         }
     }
 
+    // Change optimization mode for the indoor route calculation.
     private void onRouteModeChanged() {
         if (fastRadioButton.isChecked()) {
             routeOptions.routeOptions.optimizationMode = OptimizationMode.FASTEST;
@@ -318,6 +363,7 @@ private void onRouteModeChanged() {
         }
     }
 
+    // Change transport mode for the indoor route calculation.
     private void onTransportModeChanged() {
         if (pedestrianRadioButton.isChecked()) {
             routeOptions.transportMode = IndoorTransportMode.PEDESTRIAN;
@@ -326,6 +372,7 @@ private void onTransportModeChanged() {
         }
     }
 
+    // Change walking speed for the indoor route calculation.
     private boolean onWalkSpeedEditorAction(TextView textView, int actionId, KeyEvent event) {
         if (actionId == EditorInfo.IME_ACTION_SEARCH || actionId == EditorInfo.IME_ACTION_DONE ||
             event != null && event.getAction() == KeyEvent.ACTION_DOWN &&
@@ -353,6 +400,7 @@ private boolean onWalkSpeedEditorAction(TextView textView, int actionId, KeyEven
         return false;
     }
 
+    // Adds or removes avoidance features for indoor route calculation.
     private void onAvoidFeatureChanged(View view) {
         CheckBox checkBox = (CheckBox) view;
         if (checkBox == null) {
@@ -371,6 +419,7 @@ private void onAvoidFeatureChanged(View view) {
         }
     }
 
+    // Get an indoor feature based on the name.
     private IndoorFeatures getIndoorFeature(String checkboxName) throws IllegalStateException {
         switch (checkboxName) {
         case "Elevator":