Types of map objects
The Maps API comes with an object model, which provides a convenient means to organize objects on the map. The API distinguishes between three different types of objects: markers, spatials and groups.
Markers are objects that visually indicate locations on the map, therefore each marker is defined by the geographical point (latitude and longitude) to which it is anchored, and it includes an icon. Panning the map changes the position of the marker on the screen, but the size of the marker icon remains constant when you change the map zoom level (if you zoom in or out).
The API offers two types of markers to cater to different scenarios:
- normal marker (
- DOM marker (
For further details, see Marker Objects.
Spatials (spatial objects, also referred to as geo shapes in this guide) are circles, rectangles, polylines and polygons and can be used to mark areas on the map. A spatial object is defined by a set of geographical points. The points are translated and scaled as the map is panned and zoomed so that the position of the shape on the display faithfully reflects its geographic location. A spatial object includes styling information, which determines how to trace its outlines and how to fill it (if it is a closed shape).
The Maps API offers the following classes that represent spatial objects:
- Polylines (
- Polygons (
- Circles (
- Rectangles (
For more information, see Geo Shapes.
Overlay is an object that covers a rectangular area on the map with the bitmap image and is defined by a set of geographical points. The image can be procedurally generated or a static bitmap fetched from the server.
For more information, see Overlays.
Groups are logical containers that can hold a collection of child objects (markers or spatials, but also sub-groups). Groups make it easy to add, remove, show or hide whole sets of map objects in an atomic operation, without the need to manipulate each object individually. In addition, a group allows you to calculate a bounding box enclosing all the objects it contains and to listen for events dispatched by the group's child objects.
Adding and removing objects
Each map object type corresponds to a class in the API. A newly created instance of such a class does not automatically appear on the map, but, like a node in the HTML document object model (DOM), must be added to the root. This means that to make an object appear on the map, it must be added to the map's root group through a call to the map object's method
addObject(). Conversely, to remove an object from the map, a call to the map object's method
removeObject() is required.
Groups have their own
removeObject() methods and behave like container elements in the HTML document object model. It is possible to add an empty group to the map and add individual objects later.
The code below demonstrates how to create an empty group, add it to the map, then create a marker and make it a member of the group.
group = new H.map.Group();
marker = new H.map.Marker(map.getCenter());
Markers (normal markers) and finally all