UI controls

VERSION 0.3.1056
PUBLIC PREVIEW

The Map Display module provides a set of built-in UI elements that can be used to control the map. The components can be accessed and customized by using the TomTomMap object. Each of these elements can be repositioned by changing its margin property (expressed in pixels).

The UI components can be modified not only in the Kotlin code, but also in the XML styles. To modify them in XML, use the appropriate style and parent names as described below. You can use this method to set Android properties as well as attributes defined in the Map Display module.

Compass

The compass graphic indicates which way is north. By default, it is placed in the upper right corner of the map and is only visible when the map is not oriented north-up. If the user clicks the compass, the camera rotates to the north up position. The icon changes to the northUpIcon then disappears with an animation. You can set your drawable as an icon that points north when the map is not north-up. When the map is north-up, the icon becomes the northUpIcon.

Compass button

Use the visibilityPolicy of the CompassButton to change the default visibility policy.

.

To detect a click on the compass button, set the OnUiComponentClickListener.

.

Once the click listener is no longer needed, it can be removed.

.

To change the style of the CompassButton in XML, set the style name to CompassButton and its parent to BasicCompassButton.

1<style name="CompassButton" parent="BasicCompassButton">
2 <item name="android:backgroundTint">@android:color/black</item>
3 <item name="compassButton_visibilityPolicy">visible</item>
4</style>

Zoom controls

When visible, the zoom control is in the middle of the right-hand side of the map. It is invisible by default, but you can change it using the isVisible flag on the ZoomControlsView.

.

Zoom controls

You can also set your custom drawable as the zoom in and zoom out icons.

.

To modify the zoom components in XML, use ZoomControlsView as the style name and BasicZoomControlsView as its parent.

1<style name="ZoomControlsView" parent="BasicZoomControlsView">
2 <item name="android:visibility">visible</item>
3 <item name="zoom_controls_zoomInIcon">@drawable/ic_cafe</item>
4 <item name="android:layout_gravity">start</item>
5</style>

Current location button

Users can clicking the current location button to re-center the camera on the device location.

To work, the button needs access to that location. This is obtained by setting the LocationProvider to the map using the TomTomMap.setLocationProvider(LocationProvider) method. See the Showing user location guide for more information.

By default, the button is in the bottom left corner of the map and is visible whenever the map is not centered on the device location.

Location button

To change the visibility of the button use the visibilityPolicy of the CurrentLocationButton.

.

You can also set a custom drawable as an icon at the current location.

.

As with the CompassButton, you can listen to click events performed on the CurrentLocationButton.

.

The OnUiComponentClickListener can be removed when listening to click events is no longer needed.

.

Customizing CurrentLocationButton in the XML requires using CurrentLocationButton as the style name and BasicCurrentLocationButton as its parent.

1<style name="CurrentLocationButton" parent="BasicCurrentLocationButton">
2 <item name="android:src">@drawable/ic_cafe</item>
3 <item name="currentLocationButton_visibilityPolicy">visible</item>
4</style>

Scale view

The scale view is located in the lower right corner by default. It appears when zooming in or out, then disappears after 5 seconds without any map interaction. It also disappears when the map is tilted or when the scale is out of range.

The scale range is 10 m to 1000 km (metric) / 30 ft to 620 mi (imperial).

Scale view

The units are set to metric or imperial based on system settings. You can change them by modifying the units property.

.

You can also remove it from the map by setting the isVisible flag to false.

.

The Scale view can be customized in the XML by setting the ScaleView style. The ScaleView style must have the BasicScaleView as a parent.

1<style name="ScaleView" parent="BasicScaleView">
2 <item name="scale_view_units">Metric</item>
3 <item name="android:background">#FFFFFF</item>
4</style>

You can also style the text of the Scale view separately using the ScaleTextView style with a parent of BasicScaleTextView.

1<style name="ScaleTextView" parent="BasicScaleTextView">
2 <item name="scale_text_stroke_color">#F7B84F</item>
3 <item name="scale_text_stroke_width">4dp</item>
4 <item name="scale_text_value_font_size">32sp</item>
5 <item name="scale_text_unit_font_size">18sp</item>
6 <item name="android:layout_width">wrap_content</item>
7 <item name="android:layout_height">wrap_content</item>
8</style>

Custom scale view

Logo view

The TomTom logo is displayed by default in the bottom left corner of the map.

Logo view

You can change its visibility by changing its visibilityPolicy.

.

To check whether the logo is visible use the isVisible property.

.

Next steps

Since you have learned how to use the map UI elements, here are recommendations for the next steps: