Map Events Handling

MapEventsManagerService is a util service for managing all the map events (click, mouse up, etc.). It exposes a simple API for entity selection, event priority management and adds custom events (drag and drop, long press).

Usage:

@Component(...)
export class SomeComponent{
constructor(private eventManager: MapEventsManagerService){
// Input about the wanted event
const eventRegistration: EventRegistrationInput = {
event: CesiumEvent.LEFT_CLICK, // event type enum. [required!]
modifier: CesiumEventModifier.CTRL, // event modifier enum. [optional]
entityType: AcEntity, // raise event only if AcEntity is clicked. [optional]
priority: 0, // event priority, default 0 . [optional]
pick: PickOptions.PICK_FIRST // entity pick option, default PickOptions.NO_PICK. [optional]
};
const clickEvent = this.eventManager.register(eventRegistration).subscribe((result) => {
// The EventResult will contain:
// movement(screen location of the event), entities(your entities) , primitives( cesium primitives, like label,billboard...)
console.log('map click', result.movement, 'primitives:', result.primitives, 'entities', result.entities);
});
}
}

In the example above we start listing to Click events. according to EventRegistration object.

  • eventManager.register()

    • Returns RxJs observer of type DisposableObservable<EventResult> that we can subscribe to.

    • To remove the event registration just do: resultObserver.dispose()

EventRegistration API

  • event: according to CesiumEvent enum. All cesium events are supported, includes additional events like drag & drop and long press

  • entityType: it is possible to register to events on a specific entities types, e.g raise event only when TrackEntity is Clicked.

    • AcEntity is the base class for all angular-cesium entities, it is a part of AcNotification and is required for MapEventManager to work properly.

    • All entities should inherit from AcEntity e.g class TrackEntity extends AcEntity {}

  • Priority: by setting the priority you can register same events and only the one with the higher priority will be raised. For example lets say when you left_click on the map a context menu should appear but if you in a drag and drop state you want that left_click will raise a drop event only, you can achieve this by setting different priority to each event.

  • PickOptions: according to the PickOptions enum, set the different strategies for picking entities on the map:

    • NO_PICK - Will not pick entities

    • PICK_FIRST - First entity will be picked . use Cesium.scene.pick()

    • PICK_ONE - If few entities are picked plonter is resolved. use Cesium.scene.drillPick()

    • PICK_ALL - All entities are picked. use Cesium.scene.drillPick()

How to inject the service

MapEventsManagerService is provided by <ac-map/>, therefor has few possibilities to reach it:

  • In any components under <ac-map/> hierarchy as seen in the example above (recommended).

  • Using @viewChild and ac-map reference: acMapComponent.getMapEventManagerService() .

All cesium map events run outside of angular zone

Meaning that the the callback that you pass to map event manager will be executed outside of angular zone. That is because Cesium run outside of Angular zone in case for performance reasons , kind of ON_PUSH strategy. For example if you update your html template for every map event and you want it to render, you should use ChangeDetectorRef or wrap your function with NgZone.run()

class MyComponent {
constructor(eventManager: MapEventsManagerService, ngZone: NgZone){
eventManager.register(eventRegistration).subscribe((result) => {
ngZone.run(()=>{
this.textShownInTheTemplateHtml = result.movment;
});
});
}
}

Plonter

In case a two or more entities are in the same location and both are clicked you have a plonter (which entity should be picked?). This is resolved according to the PickOptions that we pass to the event registration:

  • PickOptions.NO_PICK - non of the entities will be picked, you only interested in the map location.

  • PickOptions.PICK_FIRST - the first(upper) entity will be picked.

  • PickOptions.PICK_ALL - all entities are picked and returned.

  • PickOptions.PICK_ONE - only one should be picked, a context will appear allowing the client to choose which entity he wants, selected entity will be passed to the eventcall back.

plonter context-menu

angular-cesium comes with ac-default-plonter a basic implementation for the plonter context menu. showing a list of entities names to select from.

It is possible to create your own plonter context menu just take a look at ac-default-plonter implementation, and disable the default plonter:

<ac-map [disableDefaultPlonter]="true"></ac-map>

Examples