Display markers
The base class for the marker hierarchy is Marker. It encapsulates coordinates assigned to a specific part. Multiple coordinates can be added to the same marker and be separated into different parts. If no part is specified, the coordinates are added to a default part, indexed as 0. The coordinates are stored in a list-like structure, where you can specify their index explicitly. By default, the index is set to -1, meaning the coordinate will be appended to the end of the list.
// code used for displaying a marker with coordinates separated into different parts
auto marker = Marker();
marker.add(Coordinates(52.1459, 1.0613), -1, 0);
marker.add(Coordinates(52.14569, 1.0615), -1, 0);
marker.add(Coordinates(52.14585, 1.06186), -1, 1);
marker.add(Coordinates(52.14611, 1.06215), -1, 1);
// code used for displaying a marker with coordinates added to the same part
auto marker = Marker();
marker.add(Coordinates(52.1459, 1.0613), -1, 0);
marker.add(Coordinates(52.14569, 1.0615), -1, 0);
marker.add(Coordinates(52.14585, 1.06186), -1, 0);
marker.add(Coordinates(52.14611, 1.06215), -1, 0);
To display any type of marker on a map, it must first be added to a MarkerCollection. Creating a collection of markers requires providing a name and specifying the desired EMarkerType enum as parameters for its constructor. The collection of markers displayed above used EMarkerType::MT_Polyline, but it can also be EMarkerType::MT_Point or EMarkerType::MT_Polygon.
Once the MarkerCollection object has been populated, it must be added to the MapViewMarkerCollections field within the MapViewPreferences class. This can be accessed through the MapView, as shown below:
mapView->preferences().markers().add(markerCollection);
Point Type Marker
Visually represented as an icon, it is used to dynamically highlight user-defined locations. To display a point-type marker, the MarkerCollection to which the markers are added must be of the MarkerType.point type.
auto marker = Marker();
marker.add(Coordinates(52.1459, 1.0613), -1, 0);
marker.add(Coordinates(52.14569, 1.0615), -1, 0);
marker.add(Coordinates(52.14585, 1.06186), -1, 1);
marker.add(Coordinates(52.14611, 1.06215), -1, 1);
auto markerCollection = MarkerCollection( EMarkerType::MT_Point, "myCollection");
markerCollection.add(marker);
mapView->preferences().markers().add(markerCollection);
mapView->centerOnArea(markerCollection.getArea(), 90);
The result will be the following:
By default, point-type markers appear as blue circles up to a specific zoom level. When the zoom threshold is exceeded, they automatically cluster into orange circles, and at higher levels of clustering, they transition to red circles. Learn more at Marker Clustering
Polyline Type Marker
This type of marker is designed to display a continuous line consisting of one or more connected straight-line segments. To use it, ensure the MarkerCollection specifies markerType as EMarkerType::MT_Polyline. It's important to note that markers can include multiple coordinates, which may or may not belong to the same part. Coordinates within the same part are connected by a polyline, which is red by default, while coordinates outside the part remain unconnected.
For more information, see Markers section.
Polygon Type Marker
This type of marker is designed to display a closed two-dimensional figure composed of straight-line segments that meet at their endpoints. To use it, ensure the MarkerCollection specifies markerType as EMarkerType::MT_Polygon.
To successfully create a polygon, at least three coordinates must be added to the same part. Otherwise, the result will be an open polyline rather than a closed shape.
Polygons can be customized using properties like polygonFillColor and polygonTexture. Additionally, since polygon edges are essentially polylines, you can further refine their appearance with polyline-related attributes such as polylineInnerColor, polylineOuterColor, polylineTexture, and more.
Marker Customizations
To customize the appearance of markers on MapView, you can use the MarkerCollectionRenderSettings class.
This class is designed for customizing the appearance of individual markers. It includes various fields that can influence a marker's appearance, regardless of its type, as it provides customizable features for all marker types. For example:
- For markers of type
EMarkerType::MT_Polyline, you can use fields such aspolylineInnerColor,polylineOuterColor,polylineInnerSize, andpolylineOuterSize. - For
EMarkerType::MT_Polygon, thepolygonFillColor,polygonTexturefields are available, among others. - For
EMarkerType::MT_Point, you can use fields such aslabelTextColor,labelTextSize,image,imageSize.
All dimensional sizes (imageSize, labelTextSize, etc.) are measured in millimeters.
If customizations unrelated to a marker's specific type are applied - for example, using polylineInnerColor for a EMarkerType::MT_Point-they will simply be ignored, and the marker's appearance will remain unaffected.
For EMarkerType::MT_Point, a key customizable field is labelingMode. This field is a set that consists of values from EMarkerLabelingMode enum. This allows you to enable desired features, such as positioning the label text above the icon or placing the icon above the marker's coordinates, by adding them to the labelingMode set as shown below:
auto renderSettings = MarkerCollectionRenderSettings();
renderSettings.labelingMode = EMarkerLabelingMode::MLM_ItemLabelVisible |
EMarkerLabelingMode::MLM_TextAbove |
EMarkerLabelingMode::MLM_IconBottomCenter;
mapView->preferences().markers().add(markerCollection, renderSettings);
To hide/show a marker's name or its group's name, create a MarkerCollectionRenderSettings object with a labelingMode that excludes/includes EMarkerLabelingMode::MLM_ItemLabelVisible and EMarkerLabelingMode::MLM_GroupLabelVisible.
The above code will result in the following marker appearance:
To assign a name to a marker, use the name setter of the Marker class.
To customize the icons of the displayed markers, add the collection to MapViewMarkerCollections and configure a MarkerCollectionRenderSettings instance with the relevant image field. This field controls the appearance of the entire collection.
Image image = Image(image::Core::Search_Results_Pin);
auto renderSettings = MarkerCollectionRenderSettings(image);
Code above is setting a custom icon to a marker. The result is the following:
Marker Sketches
To customize the appearance of each marker individually, use the MarkerSketches class, which extends MarkerCollection. This lets you define unique styles and properties for every marker. You can obtain a MarkerSketches object using the MapViewMarkerCollections::sketches() method:
auto sketches = mapView->preferences().markers().sketches(EMarkerType::MT_Point);
Typical operations are adding a sketch with an optional per‑marker render configuration and position, reading a sketch’s rendering configuration.
There are only three MarkerSketches collections, one for each marker type: EMarkerType::MT_Point, EMarkerType::MT_Polyline, and EMarkerType::MT_Polygon. Each collection is singleton.
Adding markers to a MarkerSketches collection is similar to adding them to a MarkerCollection. However, when adding markers to a MarkerSketches collection, you can specify individual MarkerRenderSettings and index for each marker. This allows for greater customization of each marker's appearance.
auto marker1 = Marker();
marker1.add(Coordinates(39.76741, -46.8962));
marker1.setName("HelloMarker");
auto sketches = mapView->preferences().markers().sketches( EMarkerType::MT_Point );
MarkerRenderSettings renderSettings;
renderSettings.setLabelingMode( EMarkerLabelingMode::MLM_ItemLabelVisible |
EMarkerLabelingMode::MLM_TextAbove |
EMarkerLabelingMode::MLM_IconBottomCenter );
renderSettings.setLabelTextColor( Rgba( 255, 0, 0, 255 ) );
renderSettings.setLabelTextSize( 3.0 );
renderSettings.setImage( Image( image::Core::Search_Results_Pin ) );
sketches.add(marker1, renderSettings, 0);
mapView->centerOnArea( sketches.getArea(), 90 );
In order to change a marker's appearance after it has been added to a MarkerSketches collection, you can use setRenderSettings method:
sketches.setRenderSettings(
0, // marker index
newRenderSettings)
);
In order to obtain the current render settings of a marker, you can use getRenderSettings method called with the marker index:
const MarkerRenderSettings* returnedSettings = sketches.getRenderSettings(0);
Calling getRenderSettings with an invalid index will return a null MarkerRenderSettings object.
The MarkerSketches collection does not need to be added to MapViewMarkerCollections, as it is already part of it. Any changes made to the MarkerSketches collection will be automatically reflected on the map.
Adding a MarkerSketches object to MapViewMarkerCollections with MarkerCollectionRenderSettings will be overwritten by the individual MarkerRenderSettings of markers from the collection.
Marker Clustering
Clustering or grouping is a default feature of markers. Beyond a certain zoom level, the markers automatically cluster into a single marker containing a number of items lesser than lowGCount default value if the group is a low density one. The image of those groups can be customized with lowDensityPointsGroupImage, mediumDensityPointsGroupImage, highDensityPointsGroupImage fields of MarkerCollectionRenderSettings. The number of markers contained by a group can be set through lowDensityPointsGroupMaxCount, mediumDensityPointsGroupMaxCount.
// code for markers not grouping at zoom level 70
mapView->preferences().markers().add(markerCollection);
mapView->centerOnArea(markerCollection.getArea(), 70);
// code for markers grouping at zoom level 70
auto renderSettings = MarkerCollectionRenderSettings();
renderSettings.setLabelingMode( EMarkerLabelingMode::MLM_None ); // don't display a label
renderSettings.pointsGroupingZoomLevel = 70;
mapView->preferences().markers().add(markerCollection, renderSettings);
mapView->centerOnArea(markerCollection.getArea(), 70);
You can disable marker clustering by setting the pointGroupingZoomLevel to 0. However, note that doing so for a large number of markers may significantly impact performance, as rendering each individual marker increases GPU resource usage.
Marker clusters are represented by the first marker from the collection as the group head. The group head marker is returned by the getPointsGroupHead method:
auto markerCollection = MarkerCollection(EMarkerType::MT_Point, "Collection1");
auto marker1 = Marker(Coordinates(39.76717, -46.89583), "Name1");
auto marker2 = Marker(Coordinates(39.767138, -46.895640), "Name2");
auto marker3 = Marker(Coordinates(39.767145, -46.895690), "Name3");
markerCollection.add(marker1);
markerCollection.add(marker2);
markerCollection.add(marker3);
auto renderSettings = MarkerCollectionRenderSettings();
renderSettings.buildPointsGroupConfig = true;
mapView->preferences().markers().add( markerCollection, renderSettings );
// This centering triggers marker grouping
mapView->centerOnCoordinates(Coordinates( 39.76717, -46.89583), 50);
// Give the example some time to run
WAIT_TIME_OUT(250);
auto marker = markerCollection.getPointsGroupHead(marker2.getId()); // Returns marker1
Since marker grouping depends on the loading of tiles at a certain zoom level, you need to wait for them to load; otherwise, calling getPointsGroupHead will return a reference to the queried marker, because the markers are not yet grouped. Thus markerCollection.getPointsGroupComponents will return an empty list.
This behavior occurs only when the MarkerCollection is added to MapViewMarkerCollections using MarkerCollectionRenderSettings::buildPointsGroupConfig true and the markers are grouped based on the zoom level. In all other cases, the method returns a direct reference to the queried marker.
All markers from a group can be returned by using getPointsGroupComponents method called with the head marker id, returned by MarkerCollection::getPointsGroupHead method, which is considered the groupId. This method returns all markers except the group head marker.
auto marker = markerCollection.getPointsGroupHead(marker2.getId());
auto groupMarkers =
markerCollection.getPointsGroupComponents(marker.getId());
If getPointsGroupComponents is not invoked with the ID of the group head marker, the method will return an empty list.