Sorry, you need to enable JavaScript to visit this website.

Balloons

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 corresponding balloon to display detailed information.
Balloon can be triggered in two ways:

  • Automatically, if the annotation is tapped on the map

  • Calling 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 build in balloon views that provide easy way to display it, like SimpleMarkerBalloon
that is used to display default balloon.
A balloon object is an instance of MarkerBalloon that has to implement ViewAdapter interface.

Default Balloons

By default every marker when selected will display default balloon which is instance of BaseMarkerBalloon
filled with coordinates of 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");

Model can be used to inflate balloon view.

Property Marker#canShowBalloon by default is set to true. By changing it to false marker can still
be selected but no balloon will appear.
Property Marker#selected determines if 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 key can be added.

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

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

/**
 * Adapter of balloon view. Implement interface to inflate balloon adapter.
 */
public interface BalloonViewAdapter<T extends MarkerBalloon> {

    /**
     * Callback which is call when inflating model.
     *
     * @param container - container where marker or balloon item will be inflated
     * @param marker - marker which has a balloon
     * @param markerBalloon - view model of marker balloon
     */
    <M extends T> View onCreateView(ViewGroup container, Marker marker, M markerBalloon);

    /**
     * @param view  the root view of inflating layout
     * @param marker value which is used to fill layout
     * @param markerBalloon view model of the marker balloon
     */
    <M extends T> void onBindView(View view, Marker marker, M markerBalloon);

    /**
     * View of the marker balloon
     * @return can be null when balloon is not inflated yet.
     */
    View getBalloonView();

    /**
     * Get balloon offset from tke marker.
     */
    @NonNull
    Point getBalloonOffset(Marker marker);
}

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

Simple balloons

 

image
Figure 1. Simple balloon

 

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

  1. Create a model for the marker balloon with text properties: new SimpleMarkerBalloon("Welcome to TomTom")

  2. Create a balloon view adapter: TextBalloonViewAdapter supports one text line balloon view model.

  3. Set an adapter.

  4. All steps bellow:

tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new TextBalloonViewAdapter());
SimpleMarkerBalloon balloon = new SimpleMarkerBalloon("Welcome to TomTom");
MarkerBuilder markerBuilder = new MarkerBuilder(Locations.AMSTERDAM_LOCATION)
        .markerBalloon(balloon);

Marker m = tomtomMap.addMarker(markerBuilder);
balloon.setText("Welcome to TomTom");

 

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

Custom balloons

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

image

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.

  • All steps bellow:

tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new SingleLayoutBalloonViewAdapter(R.layout.custom_balloon_layout));
MarkerBuilder markerBuilder = new MarkerBuilder(Locations.AMSTERDAM_LOCATION)
        .markerBalloon(new BaseMarkerBalloon());
Marker m = tomtomMap.addMarker(markerBuilder);

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

/**
 * @param view  the root view of inflating layout
 * @param marker value which is used to fill layout
 * @param markerBalloon view model of the marker balloon
 */
<M extends T> void onBindView(View view, Marker marker, M markerBalloon);

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