Événements

Le SDK Maps pour Android vous permet d'écouter des événements qui se produisent sur la carte.

Exemples de code

Le référentiel ApiDemos sur GitHub inclut des exemples qui montrent comment fonctionnent les événements et les écouteurs :

Événements liés aux clics sur la carte et aux clics longs

Si vous voulez répondre à un utilisateur qui appuie sur un point de la carte, vous pouvez utiliser un OnMapClickListener que vous pouvez définir sur la carte en appelant GoogleMap.setOnMapClickListener(OnMapClickListener). Lorsqu'un utilisateur clique sur un endroit de la carte (appuie), vous recevez un événement onMapClick(LatLng) qui indique le point géographique de la carte sur lequel l'utilisateur a cliqué. Notez que si vous avez besoin d'obtenir le point géographique correspondant sur l'écran (en pixels), vous pouvez obtenir une Projection sur la carte qui vous permet de convertir les coordonnées de latitude/longitude en coordonnées en pixels à l'écran.

Vous pouvez également écouter les événements de clic long avec un OnMapLongClickListener que vous pouvez définir sur la carte en appelant GoogleMap.setOnMapLongClickListener(OnMapLongClickListener). Cet écouteur se comporte de la même façon que l'écouteur de clic et sera averti des événements de clic long avec un rappel onMapLongClick(LatLng).

Désactiver les événements de clic en mode simplifié

Pour désactiver les événements de clic sur une carte en mode simplifié, appelez setClickable() sur la vue contenant le MapView ou le MapFragment. Cela est utile, par exemple, pour afficher une ou plusieurs cartes sous forme de liste, où l'événement de clic doit appeler une action sans rapport avec la carte.

L'option permettant de désactiver les événements de clic est disponible en mode simplifié uniquement. La désactivation des événements de clic rend également les repères non cliquables. Elle n'a aucun impact sur les autres commandes de la carte.

Pour une MapView :

MapView view;
...
view.setClickable(false);

Pour une MapFragment :

MapFragment fragment;
...
fragment.getView().setClickable(false);

Événements liés aux changements de caméra

La vue de la carte est modélisée comme une caméra orientée vers le bas sur une surface plane. Vous pouvez modifier les propriétés de la caméra pour agir sur le niveau de zoom, la fenêtre d'affichage et la perspective de la carte. Consultez le guide dédié à caméra. Les utilisateurs peuvent également agir sur l'appareil photo par le biais de gestes.

Les écouteurs de changement de caméra vous permettent de réaliser un suivi des mouvements de la caméra. Votre application peut recevoir des notifications qui lui signalent les événements de mouvement de la caméra (début, fin et mouvement en cours). Vous pouvez également voir pourquoi la caméra se déplace (gestes de l'utilisateur, animations intégrées à l'API ou mouvements commandés par les développeurs).

L'exemple de code suivant illustre tous les écouteurs d'événement de caméra disponibles :

public class MyCameraActivity extends FragmentActivity implements
        OnCameraMoveStartedListener,
        OnCameraMoveListener,
        OnCameraMoveCanceledListener,
        OnCameraIdleListener,
        OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_my_camera);

        SupportMapFragment mapFragment =
            (SupportMapFragment) getSupportFragmentManager()
                    .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        mMap.setOnCameraIdleListener(this);
        mMap.setOnCameraMoveStartedListener(this);
        mMap.setOnCameraMoveListener(this);
        mMap.setOnCameraMoveCanceledListener(this);

        // Show Sydney on the map.
        mMap.moveCamera(CameraUpdateFactory
                .newLatLngZoom(new LatLng(-33.87365, 151.20689), 10));
    }

    @Override
    public void onCameraMoveStarted(int reason) {

        if (reason == OnCameraMoveStartedListener.REASON_GESTURE) {
            Toast.makeText(this, "The user gestured on the map.",
                           Toast.LENGTH_SHORT).show();
        } else if (reason == OnCameraMoveStartedListener
                                .REASON_API_ANIMATION) {
            Toast.makeText(this, "The user tapped something on the map.",
                           Toast.LENGTH_SHORT).show();
        } else if (reason == OnCameraMoveStartedListener
                                .REASON_DEVELOPER_ANIMATION) {
            Toast.makeText(this, "The app moved the camera.",
                           Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public void onCameraMove() {
        Toast.makeText(this, "The camera is moving.",
                       Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onCameraMoveCanceled() {
        Toast.makeText(this, "Camera movement canceled.",
                       Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onCameraIdle() {
        Toast.makeText(this, "The camera has stopped moving.",
                       Toast.LENGTH_SHORT).show();
    }
}

Les écouteurs de caméra suivants sont disponibles :

  • Le rappel onCameraMoveStarted() de OnCameraMoveStartedListener est invoqué lorsque la caméra commence à se déplacer. La méthode de rappel reçoit le motif (reason) du mouvement de la caméra. Le motif peut être l'un des suivants :

    • REASON_GESTURE indique que la caméra s'est déplacée en réponse à un geste de l'utilisateur sur la carte (panoramique, inclinaison, zoom par pincement ou rotation de la carte, par exemple).
    • REASON_API_ANIMATION indique que l'API a déplacé la caméra en réponse à une action non gestuelle de l'utilisateur (appui sur le bouton de zoom, sur le bouton Ma position ou sur un repère).
    • REASON_DEVELOPER_ANIMATION indique que votre application a initié le mouvement de la caméra.
  • Le rappel onCameraMove() de OnCameraMoveListener est invoqué plusieurs fois lorsque la caméra se déplace ou que l'utilisateur interagit avec l'écran tactile. Pour vous faire une idée de la fréquence à laquelle les rappels sont invoqués, notez que l'API invoque le rappel une fois par cadre. Toutefois, ce rappel est invoqué de manière asynchrone. Il n'est donc pas synchronisé avec ce qui est visible à l'écran. En outre, il est possible que la caméra ne change pas de position entre un rappel onCameraMove() et le suivant.

  • Le rappel OnCameraIdle() de OnCameraIdleListener est invoqué lorsque la caméra cesse de se déplacer et que l'utilisateur n'interagit plus avec la carte.

  • Le rappel OnCameraMoveCanceled() de OnCameraMoveCanceledListener est invoqué en cas d'interruption du déplacement de la caméra. Immédiatement après le rappel OnCameraMoveCanceled(), le rappel onCameraMoveStarted() est invoqué avec le nouveau reason.

    Si votre application appelle explicitement GoogleMap.stopAnimation(), le rappel OnCameraMoveCanceled() est invoqué, mais le rappel onCameraMoveStarted() n'est pas invoqué.

Pour définir un écouteur sur la carte, appelez la méthode de définition d'écouteur appropriée. Par exemple, pour demander un rappel à partir de OnCameraMoveStartedListener, appelez GoogleMap.setOnCameraMoveStartedListener().

Pour obtenir la cible de la caméra (latitude/longitude), le niveau de zoom, la direction et l'inclinaison, vous pouvez utiliser CameraPosition. Consultez le guide dédié à la position de la caméra pour en savoir plus sur ces propriétés.

Événements liés aux établissements et aux autres points d'intérêt

Par défaut, les points d'intérêt (POI) sont affichés sur la carte de base avec les icônes qui leur correspondent. Les POI comprennent d'une part les parcs, écoles, bâtiments administratifs, etc., et d'autre part les POI de type "établissement" (magasins, restaurants et hôtels, par exemple).

Vous pouvez répondre aux événements de clic sur un POI. Consultez le guide sur les établissements et autres points d'intérêt.

Événements liés aux plans d'intérieur

Vous pouvez utiliser des événements pour rechercher et personnaliser le niveau actif d'un plan d'intérieur. Utilisez l'interface OnIndoorStateChangeListener pour définir un écouteur à appeler lorsqu'un nouveau bâtiment est placé au centre ou qu'un nouveau niveau est activé dans un bâtiment.

Obtenez le bâtiment qui se trouve actuellement au centre en appelant GoogleMap.getFocusedBuilding(). Le fait de centrer la carte sur une latitude/longitude spécifique vous permet en général d'obtenir le bâtiment se trouvant à cette latitude/longitude, mais ce n'est pas garanti.

Vous pouvez alors trouver le niveau actuellement actif en appelant IndoorBuilding.getActiveLevelIndex().

IndoorBuilding building = mMap.getFocusedBuilding();
if (building == null) {
  return null;
}
return building.getLevels().get(building.getActiveLevelIndex());

Cela s'avère utile si vous souhaitez afficher un balisage personnalisé pour le niveau actif, comme des repères, des superpositions au sol, des superpositions de tuiles, des polygones, des polylignes, et d'autres formes.

Conseil : Pour revenir au niveau de la rue, obtenez le niveau par défaut via IndoorBuilding.getDefaultLevelIndex() et définissez-le comme niveau actif via IndoorLevel.activate().

Événements liés aux repères et aux fenêtres d'informations

Vous pouvez écouter et répondre aux événements de repère, y compris aux événements de clic et de déplacement de repère, en définissant l'écouteur correspondant sur l'objet GoogleMap auquel le repère appartient. Consultez le guide des événements de repère.

Vous pouvez également écouter les événements sur les fenêtres d'informations.

Événements liés aux formes et aux superpositions

Vous pouvez écouter et répondre aux événements de clic sur les polylines, les polygones, les cercles et les superpositions au sol.

Événements liés à la localisation

Votre application peut répondre aux événements suivants liés au calque Ma position :

Pour plus d'informations, consultez le guide dédié au calque Ma position.