# Annotation

> **Note (legacy): Not compatible with the Maps SDK v10**
> 
> This plugin is not compatible with the Maps SDK v10 or higher. The Maps SDK v10 and higher comes with annotation functionality built in. See the [Markers and annotations](https://docs.mapbox.com/android/maps/guides/annotations/) guide.

The **Annotation Plugin for Android** simplifies the way to set and adjust the visual properties of annotations on a Mapbox map. The [Mapbox Maps SDK for Android](https://docs.mapbox.com/help/glossary/mapbox-android-sdk/) provides you with fine-grained control over the appearance and location of map annotations.

In this context, "annotations" means circles, polygons, lines, text, and icons. Using runtime styling and data-driven styling to create annotations can require a deep understanding of the Mapbox Maps SDK. This plugin obfuscates much of the required boilerplate code.

*Note: A [`SymbolLayer`](https://docs.mapbox.com/legacy/maps/api/9.7.1/com/mapbox/mapboxsdk/style/layers/SymbolLayer.html) is the [style layer](https://docs.mapbox.com/help/glossary/layer/) that handles both map text and icons.*

## Install the Annotation Plugin

To start developing an application using the Annotation Plugin, you'll need to add the appropriate dependencies inside of your `build.gradle`. The Annotation Plugin dependency includes the Mapbox Maps SDK for Android. You can find all dependencies given below on MavenCentral.

> **Note: Android's 64K method count limit**
> 
> If your application is over the 64K method limit, you can [shrink, obfuscate, and optimize your code](https://developer.android.com/studio/build/shrink-code) with R8 or ProGuard. If those steps do not lower your method count below 64K, you can also [enable multidex](https://developer.android.com/studio/build/multidex).

### Add the dependency

1.  Start Android Studio.
2.  Open up your project's `build.gradle`.
3.  Make sure that your project's `minSdkVersion` is API 14 or higher.
4.  Under dependencies, add a new build rule for the latest `mapbox-android-plugin-annotation-v9`.
5.  Click the **Sync Project with Gradle Files** near the toolbar in Studio.

```groovy
repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-annotation-v9:0.9.0'
}
```

## Initialize the plugin

The plugin includes manager classes for the various map layers available in the Mapbox Maps SDK for Android. The manager classes are explained below and their constructors only require a `MapboxMap` object. You should initialize a manager class within the `onMapReady()` method to be sure that the annotations are added to a `MapboxMap` that's completely ready.

**Java**

```java

@Override
public void onMapReady(@NonNull final MapboxMap mapboxMap) {
	mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
	  @Override
	  public void onStyleLoaded(@NonNull Style style) {

	    // Use a layer manager here


	  }
	});
}
```

**Kotlin**

```kt

override fun onMapReady(mapboxMap: MapboxMap) {
	mapboxMap.setStyle(Style.MAPBOX_STREETS) {

		// Use a layer manager here


	}
}
```

## Manager

The circle, line, fill, and symbol map layers have accompanying manager classes. Each manager class has methods for setting layer properties that are less related to the visual styling. For example, `SymbolManager` adjusts the position of the `SymbolLayer`'s icon or text with methods such as `iconAllowOverlap()` or `iconTranslate()`.

You can also set `onClick` and `onLongClick` listeners to the type of annotations that you're adding to the map.

| Layer type | Manager class |
| --- | --- |
| Circle | [`CircleManager`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/CircleManager.java) |
| Line | [`LineManager`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/LineManager.java) |
| Fill | [`FillManager`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/FillManager.java) |
| Symbol | [`SymbolManager`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/SymbolManager.java) |

### Add a manager

For example, the code below shows how you can use a `SymbolManager`. Execute this code inside of the `onStyleLoaded()` callback as described in the plugin initialization section above.

**Java**

```java

// Create symbol manager object.
SymbolManager symbolManager = new SymbolManager(mapView, mapboxMap, style);

// Add click listeners if desired.
symbolManager.addClickListener(symbol ->

);

symbolManager.addLongClickListener(symbol -> {

});

// Set non-data-driven properties.
symbolManager.setIconAllowOverlap(true);
symbolManager.setIconTranslate(new Float[]{-4f,5f});
symbolManager.setIconRotationAlignment(ICON_ROTATION_ALIGNMENT_VIEWPORT);
```

**Kotlin**

```kt

// Create symbol manager object.
val symbolManager = SymbolManager(mapView, mapboxMap, style)

// Add click listeners if desired.
symbolManager?.addClickListener { symbol ->

}

symbolManager?.addLongClickListener { symbol ->

}

// Set non-data-driven properties.
symbolManager?.iconAllowOverlap = true
symbolManager?.iconTranslate = arrayOf(-4f, 5f)
symbolManager?.iconRotationAlignment = ICON_ROTATION_ALIGNMENT_VIEWPORT
```

> **Related content (example): [Manager class usage](https://github.com/mapbox/mapbox-plugins-android/tree/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation)**
> 
> See more usage of various manager classes.

## Options

The `CircleManager`, `FillManager`, and `SymbolManager` objects can also create annotations via respective `CircleOptions()`, `FillOptions()`, and `SymbolOptions()` classes. These options classes follow the builder pattern, which allows you to set various layer properties that are more related to visual styling. For example, `FillOptions` adjusts the look of a `FillLayer` polygon with methods such as `withFillColor()`, `withFillOpacity()`, and `withFillPattern()`.

| Layer type | Option class |
| --- | --- |
| Circle | [`CircleOptions`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/CircleOptions.java) |
| Line | [`LineOptions`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/LineOptions.java) |
| Fill | [`FillOptions`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/FillOptions.java) |
| Symbol | [`SymbolOptions`](https://github.com/mapbox/mapbox-plugins-android/blob/master/plugin-annotation/src/main/java/com/mapbox/mapboxsdk/plugins/annotation/SymbolOptions.java) |

### Add a `Symbol` annotation

This example shows how to create a `Symbol` annotation with a `SymbolManager` and `SymbolOptions`.

**Java**

```java

// Create a SymbolManager.
SymbolManager symbolManager = new SymbolManager(mapView, mapboxMap, style);

// Set non-data-driven properties.
symbolManager.setIconAllowOverlap(true);
symbolManager.setTextAllowOverlap(true);

// Create a symbol at the specified location.
SymbolOptions symbolOptions = new SymbolOptions()
        .withLatLng(new LatLng(6.687337, 0.381457))
        .withIconImage(ID_ICON_AIRPORT)
        .withIconSize(1.3f)

// Use the manager to draw the symbol.
symbol = symbolManager.create(symbolOptions);
```

**Kotlin**

```kt

// Create a SymbolManager.
val symbolManager = SymbolManager(mapView, mapboxMap, style)

// Set non-data-driven properties.
symbolManager.iconAllowOverlap = true
symbolManager.iconIgnorePlacement = true

// Create a symbol at the specified location.
val symbol = symbolManager.create(SymbolOptions()
        .withLatLng(LatLng(6.687337, 0.381457))
        .withIconImage(ID_ICON_AIRPORT)
        .withIconSize(1.3f))

// Use the manager to draw the annotations.
symbolManager?.create(symbolOptions)
```

![Mapbox map with polygon annotation on an Android device.](https://docs.mapbox.com/android/assets/ideal-img/plugins-guide-annotation-symbol.3bb728d.480.png)

#### Related

-   You can see the full code for the example above in the [`SymbolActivity.java`](https://github.com/mapbox/mapbox-plugins-android/blob/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation/SymbolActivity.java) file inside the [Mapbox Plugins for Android test app](https://github.com/mapbox/mapbox-plugins-android#help-and-usage).
-   To see [all examples of option classes](https://github.com/mapbox/mapbox-plugins-android/tree/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation) for the Annotation Plugin, view the contents of the [`/testapp/activity/annotation`](https://github.com/mapbox/mapbox-plugins-android/tree/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation) folder.

### Add a `Fill` annotation

This example shows how to create a polygon annotation with a `FillManager` and `FillOptions`.

The `FillManager#create()` method can use either a single `FillOptions` object or a `List<>` of `FillOptions` as a valid parameter. This is the same for the `create()` methods for all the manager classes: `LineManager#create()` method can accept a `LineOptions` object or a `List<>` of `LineOptions`, and so on.

**Java**

```java

// Create a fixed fill rectangle around Brazil.
<LatLng> innerLatLngs = new ArrayList<>();
innerLatLngs.add(new LatLng(-35.317366, -74.179687));
innerLatLngs.add(new LatLng(-35.317366, -30.761718));
innerLatLngs.add(new LatLng(  4.740675, -30.761718));
innerLatLngs.add(new LatLng(  4.740675, -74.179687));
innerLatLngs.add(new LatLng(-35.317366, -74.179687));
<List<LatLng>> latLngs = new ArrayList<>();
latLngs.add(innerLatLngs);

// Use options to color it red.
FillOptions fillOptions = new FillOptions()
   .withLatLngs(latLngs)
   .withFillColor(ColorUtils.colorToRgbaString(Color.RED));

// Use the manager to draw the annotation.
fillManager.create(fillOptions);

// Create three random colored fills across the globe.
<FillOptions> fillOptionsList = new ArrayList<>();
for (int i = 0; i < 3; i++) {
  int color = Color.argb(255, random.nextInt(256), random.nextInt(256), random.nextInt(256));
  fillOptionsList.add(new FillOptions()
    .withLatLngs(createRandomLatLngs())
    .withFillColor(ColorUtils.colorToRgbaString(color))
    .withFillOpacity(0.8f)
  );
}

// Use the manager draw the annotations.
fillManager.create(fillOptionsList);
```

**Kotlin**

```kt

// Create a fixed fill rectangle around Brazil.
val innerLatLngs = ArrayList<LatLng>()
innerLatLngs.add(LatLng(-35.317366, -74.179687))
innerLatLngs.add(LatLng(-35.317366, -30.761718))
innerLatLngs.add(LatLng(4.740675, -30.761718))
innerLatLngs.add(LatLng(4.740675, -74.179687))
innerLatLngs.add(LatLng(-35.317366, -74.179687))

val latLngs = ArrayList<List<LatLng>>()
latLngs.add(innerLatLngs)

// Use options to color it red.
val fillOptions = FillOptions()
  .withLatLngs(latLngs)
  .withFillColor(PropertyFactory.colorToRgbaString(Color.RED))

// Use the manager to draw the annotation.
fillManager?.create(fillOptions)

// Create 20 random colored fills across the globe.
val fillOptionsList = ArrayList<FillOptions>()
for (i in 0..19) {
  val color = Color.argb(255, random.nextInt(256), random.nextInt(256), random.nextInt(256))
  fillOptionsList.add(FillOptions()
    .withLatLngs(createRandomLatLngs())
    .withFillColor(PropertyFactory.colorToRgbaString(color))
  )
}

// Use the manager to draw the annotations.
fillManager?.create(fillOptionsList)
```

![Map of the world with a red rectangle around Brazil and other random colored polygon annotations.](https://docs.mapbox.com/android/assets/ideal-img/plugins-guide-annotation-fill.299a7f9.480.png)

#### Related

-   You can see the full code for the example above in the [`FillActivity.java`](https://github.com/mapbox/mapbox-plugins-android/blob/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation/FillActivity.java) file in the [Mapbox Plugins for Android Test App](https://github.com/mapbox/mapbox-plugins-android#help-and-usage) repository on GitHub.
-   You can see more working examples of option classes in the [`/testapp/activity/annotation/`](https://github.com/mapbox/mapbox-plugins-android/blob/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation/) folder of the [Mapbox Plugins for Android](https://github.com/mapbox/mapbox-plugins-android) repository on GitHub.

## Listeners

The `CircleManager`, `FillManager`, `SymbolManager`, and `LineManager` objects also expose several listeners for user interaction. On any manager class object use these listeners `addClickListener()`, `addLongClickListener()`, and `addDragListener()`.

### Add a listener

The example below shows how to add an `addClickListener`.

**Java**

```java

symbolManager.addClickListener(new OnSymbolClickListener() {
  @Override
  public boolean onAnnotationClick(Symbol symbol) {

  }
});
```

**Kotlin**

```kt

symbolManager.addClickListener { symbol ->

}
```

#### Related

-   Example: [Symbol listener](https://docs.mapbox.com/android/legacy/plugins/examples/symbol-listener/)
-   You can see several working examples that use listeners in the [`/testapp/activity/annotation/`](https://github.com/mapbox/mapbox-plugins-android/blob/master/app/src/main/java/com/mapbox/mapboxsdk/plugins/testapp/activity/annotation/) folder of the [Mapbox Plugins for Android](https://github.com/mapbox/mapbox-plugins-android) repository on GitHub.