Balloons

Allow your users to display and customize balloons in a few lines of code.

Sample use case: You would like to learn more about a place on the map. Depending on the selected location, the app displays a balloon containing either text or additional information such as icons or pictures.

Every Marker can be linked with a corresponding balloon to display detailed information. Balloons can be triggered in two ways:

• Automatically, if the annotation is tapped on the map.
• Calling the Marker#select() method.

A balloon can be closed in the following ways:

• Automatically, if a user taps on the map.
• Automatically, if a user taps on another Marker.

You can use one of the built-in balloon views that provide an easy way to display it, like SimpleMarkerBalloon that is used to display a default balloon. A balloon object is an instance of MarkerBalloon that has to implement the ViewAdapter interface.

Default Balloons

By default every marker when selected will display a default balloon which is an instance of BaseMarkerBalloon filled with the coordinates of the marker. BaseMarkerBalloon is a view model of the marker balloon view. To add a property to the model, you need to use this function:

BaseMarkerBalloon markerBalloon = new BaseMarkerBalloon()
markerBalloon.addProperty("key", "value");

val markerBalloon = BaseMarkerBalloon()
markerBalloon.addProperty("key", "value")

Model can be used to inflate balloon view.

Property Marker#canShowBalloon by default is set to true. By changing it to false the marker can still be selected but no balloon will appear. Property Marker#selected determines if the marker is selected at all. By default is false.

There is only one defined common model property key, which can be used in BaseBalloonViewAdapter to inflate the balloon, however more property keys can be added.

1/**
2 * text property key, one of the most used properties for balloon.
3 */
4public static final String KEY_TEXT = "text";

To display a balloon model we need to create and set a balloon view adapter:

1/**
2 * The adapter of balloon view. An implement interface to inflate a balloon adapter.
3 */
4public interface BalloonViewAdapter<T extends MarkerBalloon, E extends MapPoint> {
5
6    /**
7     * A callback which is called when inflating the model.
8     *
9     * @param container - A container where a marker or balloon item will be inflated.
10     * @param marker - A marker which has a balloon.
11     * @param markerBalloon - A view model of a marker balloon.
12     */
13    <M extends T> View onCreateView(ViewGroup container, E marker, M markerBalloon);
14
15    /**
16     * @param view  The root view of inflating a layout.
17     * @param marker The value which is used to fill a layout.
18     * @param markerBalloon The view model of the marker balloon.
19     */
20    <M extends T> void onBindView(View view, E marker, M markerBalloon);
21
22    /**
23     * A view of the marker balloon.
24     * @return It can be null when the balloon is not inflated.
25     */
26    @NonNull
27    View getBalloonView();
28
29    /**
30     * Gets the balloon offset from the marker.
31     */
32    @NonNull
33    Point getBalloonOffset(E marker);
34}

There are a few implementations provided of the balloon view adapter. These implementations cover the commons cases for balloons.

Simple balloons

To create a simple balloon (a simple balloon is a balloon with one text line):

1. Create a model for the marker balloon with the text properties: new SimpleMarkerBalloon("Welcome to TomTom").
2. Create a balloon view adapter: TextBalloonViewAdapter that supports a one text line balloon view model.
3. Set an adapter.
4. Use all of the following steps:

1tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new TextBalloonViewAdapter());
2SimpleMarkerBalloon balloon = new SimpleMarkerBalloon("Welcome to TomTom");
3MarkerBuilder markerBuilder = new MarkerBuilder(position)
4        .markerBalloon(balloon);
5
6Marker m = tomtomMap.addMarker(markerBuilder);

1tomtomMap.markerSettings.markerBalloonViewAdapter = TextBalloonViewAdapter()
2val balloon = SimpleMarkerBalloon(SIMPLE_BALLOON_TEXT)
3val markerBuilder = MarkerBuilder(position)
4    .markerBalloon(balloon)
5
6val marker = tomtomMap.addMarker(markerBuilder)

If any adapter is not set by the user, TextBalloonViewAdapter is set by default. Because of that, points 2-4 are optional.

Custom balloons

Despite that you can use the default balloon, as the SDK allows you to create fully customizable ones. Balloon is nothing more than an Android layout implementation. A custom layout can be built in the way that you like either from the Android Studio Builder or programmatically.

To create a custom layout balloon:

• Create a model for the marker balloon. BaseMarkerBalloon doesn’t have properties by default. Properties can be added by the addProperties(key, value) method.
• Use SingleLayoutBalloonViewAdapter and provide the layout in the constructor.
• Set an adapter.
• Use all of the following steps:

1tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new SingleLayoutBalloonViewAdapter(R.layout.custom_balloon_layout));
2MarkerBuilder markerBuilder = new MarkerBuilder(position)
3        .markerBalloon(new BaseMarkerBalloon());
4Marker m = tomtomMap.addMarker(markerBuilder);

1tomtomMap.markerSettings.markerBalloonViewAdapter = SingleLayoutBalloonViewAdapter(layoutRes)
2val markerBuilder = MarkerBuilder(position)
3    .markerBalloon(BaseMarkerBalloon())
4
5val marker = tomtomMap.addMarker(markerBuilder)

To manage the custom ballon view model override method of SingleLayoutBalloonViewAdapter:

1/**
2 * @param view  The root view of inflating a layout.
3 * @param marker The value which is used to fill a layout.
4 * @param markerBalloon The view model of the marker balloon.
5 */
6<M extends T> void onBindView(View view, E marker, M markerBalloon);

or create your own class which extends BalloonViewAdapter and overrides all abstract methods.