Maps SDK for C++ 1.0.0
Loading...
Searching...
No Matches
gem::MapView Class Reference

MapView object - displays a map. More...

Inheritance diagram for gem::MapView:
Collaboration diagram for gem::MapView:

Public Member Functions

StrongPointer< MapCameragetCamera () const noexcept
 Retrieves the camera associated with this MapView.
MapViewPreferencesRef preferences () noexcept
 Get access to this view preferences.
MapViewskipAnimation (bool bJumpToDestination=true) noexcept
 Stop the current animation.
bool isAnimationInProgress () const noexcept
 Check if there is an animation in progress.
MapViewsetCamera (StrongPointer< MapCamera > camera) noexcept
 Set the given camera.
int maxZoomLevel () const noexcept
 Get the maximum zoom level.
double getMaxSlippyZoomLevel () const noexcept
 Get the maximum slippy zoom level.
int setZoomLevel (int zoomLevel, int duration=0, Xy xy=Xy()) noexcept
 Set a new zoom level centered on the specified screen position.
bool canZoom (int zoomLevel, Xy xy=Xy()) noexcept
 Check if it is possible to zoom at a specified zoom level.
void setMinZoomLevel (int zl) noexcept
 Set the configured min zoom level.
void setMaxZoomLevel (int zl) noexcept
 Set the configured max zoom level.
int getMinZoomLevel () const noexcept
 Get the configured min zoom level.
int getMaxZoomLevel () const noexcept
 Get the configured max zoom level.
double setSlippyZoomLevel (double zoomLevel, int duration=0, Xy xy=Xy()) noexcept
 Set a new zoom level based on slippy tile level.
int getZoomLevel () const noexcept
 Get zoom level.
double getSlippyZoomLevel () const noexcept
 Get slippy zoom level.
MapViewstartFollowingPosition (Animation animation=Animation(), int zoomLevel=-1, double viewAngle=(std::numeric_limits< double >::max)(), StrongPointer< MapSceneObject > positionObj=StrongPointer< MapSceneObject >(), CameraTrackMethod trackMethod=CameraTrackMethod()) noexcept
 Start following the current position.
MapViewstopFollowingPosition (bool restoreCameraMode=false) noexcept
 Stop following the current position.
MapViewrestoreFollowingPosition (Animation animation=Animation()) noexcept
 Restore following position from a manually adjusted mode to default auto-zoom mode.
bool isFollowingPosition (bool bAlsoFlyToPosition=true) const noexcept
 Test if following the current position mode.
bool isFollowingPositionTouchHandlerModified () const noexcept
 Test if following the current position is modified by the touch handler.
bool isDefaultFollowingPosition () const noexcept
 Test if following the current position is in default auto-zoom mode.
MapViewactivateHighlight (const LandmarkList &landmarks, const HighlightRenderSettings &renderSettings=HighlightRenderSettings(), short highlightId=0) noexcept
 Enable highlighting for the given landmark list.
MapViewactivateHighlight (const OverlayItemList &overlays, const HighlightRenderSettings &renderSettings=HighlightRenderSettings(), short highlightId=0) noexcept
 Enable the highlighting for the given overlay list.
MapViewdeactivateHighlight (short highlightId=0) noexcept
 Disable highlighting.
MapViewdeactivateAllHighlights () noexcept
 Disable all highlights.
RectangleGeographicArea getHighlightArea (int highlightId=0) const noexcept
 Get highlighted geographic area.
LandmarkList getHighlight (int highlightId) const noexcept
 Get highlighted geographic area.
MapViewcenterOnCoordinates (const Coordinates &coords, int zoomLevel=-1, Xy xy=Xy(), Animation animation=Animation(), double mapAngle=(std::numeric_limits< double >::max)(), double viewAngle=(std::numeric_limits< double >::max)()) noexcept
 Center the WGS coordinates on screen coordinates.
MapViewcenterOnCoordinates (const Coordinates &coords, Animation animation) noexcept
 Center the WGS coordinates on screen coordinates with animation.
MapViewcenterOnArea (const GeographicArea &area, int zoomLevel=-1, Xy xy=Xy(), Animation animation=Animation()) noexcept
 Center the on the given WGS area.
MapViewcenterOnArea (const GeographicArea &area, int zoomLevel, Rect viewRectangle, Animation animation=Animation()) noexcept
 Center the on the given WGS area.
MapViewcenterOnRouteInstruction (const RouteInstruction &instruction, int zoomLevel=-1, Xy xy=Xy(), Animation animation=Animation(), double viewAngle=(std::numeric_limits< double >::max)()) noexcept
 Center on the given route instruction and displays the associated turn arrow in the map view.
MapViewcenterOnRouteTrafficEvent (const RouteTrafficEvent &traffic, int zoomLevel=-1, Rect viewRectangle=Rect(), Animation animation=Animation(), double viewAngle=(std::numeric_limits< double >::max)()) noexcept
 Center on the given traffic event.
MapViewcenterOnLocation (const Landmark &location, Rect viewRectangle=Rect(), Animation animation=Animation()) noexcept
 Center on the given landmark location.
MapViewcenterOnRoute (const Route &route, Rect viewRectangle=Rect(), Animation animation=Animation()) noexcept
 Center on the given route.
MapViewcenterOnRoute (const Route &route, int startDist, int endDist, Rect viewRectangle=Rect(), Animation animation=Animation()) noexcept
 Center On the given route parts.
MapViewcenterOnRoutes (const RouteList &routesList, ERouteDisplayMode displayMode=RDM_Full, const Rect &viewRectangle=Rect(), Animation animation=Animation()) noexcept
 Center on the given routes collection.
MapViewcenterOnMapRoutes (ERouteDisplayMode displayMode=RDM_Full, const Rect &viewRectangle=Rect(), Animation animation=Animation()) noexcept
 Center on the existing routes collection.
Rect getOptimalRoutesCenterViewport (const RouteList &routesList, const Rect &viewRectangle=Rect()) const noexcept
 Gets the highlighted items optimal center viewport given the user custom input.
Rect getOptimalHighlightCenterViewport (const Rect &viewRectangle=Rect()) const noexcept
 Gets the optimal highlight center viewport given the user custom input.
Coordinates getCursorWgsPosition () const noexcept
 Get the cursor WGS coordinates.
const LandmarkListRef cursorSelectionLandmarks () const noexcept
 Retrieves a reference to a list of landmarks under the current cursor location.
const LandmarkListRef cursorSelectionStreets () const noexcept
 Retrieves a reference to a list of streets under the current cursor location.
const OverlayItemListRef cursorSelectionOverlayItems () const noexcept
 Retrieves a reference to a list of overlay items under the current cursor location.
const TrafficEventListRef cursorSelectionTrafficEvents () const noexcept
 Retrieves a reference to a list of traffic events under the current cursor location.
const RouteListRef cursorSelectionRoutes () const noexcept
 Retrieves a reference to a list of routes under the current cursor location.
const MarkerMatchListRef cursorSelectionMarkers () const noexcept
 Retrieves a reference to a list of markers under the current cursor location.
const PathRef cursorSelectionPath () const noexcept
 Retrieves the path under the current cursor location.
StrongPointer< MapSceneObject > cursorSelectionSceneObject () const noexcept
 Retrieves the scene object under the current cursor selection.
int highlightHoveredMapLabel (const Xy &pt, bool selectMapObjects) const noexcept
 Highlight the hovered map label under the given screen coordinates.
LandmarkList getNearestLocations (const Coordinates &coordinates, const IntList &lmkStores={}, int radius=0) const noexcept
 Retrieve the set of landmarks on the specified coordinates.
Xy getCursorScreenPosition () const noexcept
 Get the cursor screen position.
MapViewsetCursorScreenPosition (Xy xy) noexcept
 Set the cursor screen position.
MapViewalignNorthUp (Animation animation=Animation())
 Set the map north-up oriented.
Coordinates transformScreenToWgs (Xy xy) const noexcept
 Convert a screen coordinate to a WGS coordinate.
RectangleGeographicAreaList transformScreenToWgs (Rect const &rectangle) const noexcept
 Converts a screen rectangle to WGS areas list.
Xy transformWgsToScreen (const Coordinates &coords) const noexcept
 Convert a WGS84 coordinate to a screen coordinate.
double getAltitude (const Coordinates &coords) const noexcept
 Get altitude at the given coordinates.
std::pair< int, int > getVisibleRouteInterval (const Route &route, Rect clipRect=Rect()) const noexcept
 Get the clipped part of the given route as a pair (startDistance, endDistance).
bool checkObjectVisibility (const MapSceneObject &obj, Rect viewport=Rect()) const noexcept
 Check if the given scene object visible in the given viewport.
StyleLayerInfoList getStyleLayerInfo (const Coordinates &coords) const noexcept
 Get style layers information at the given coordinates.
StyleLegendList getStyleLegend () const noexcept
 Get style legend list ( for layers which have legends ).
bool isCameraMoving () const noexcept
 Check if view camera is moving.
MapViewsetClippingArea (const RectF &area) noexcept
 Sets the view clipping rectangle in parent screen ratio.
MapViewscroll (float dx, float dy) noexcept
 Scroll map.
MapViewfling (float velocityX, float velocityY) noexcept
 Fling / swipe map.
TransferStatisticsRef getTransferStatistics (EViewOnlineServiceType serviceType) const noexcept
 Get data transfer statistics for a given service.
MapViewExtensionsRef extensions () noexcept
 Get access to MapViewExtensions.
IMapDebugDetails * features () noexcept
 Obtain the map view features object.
IMapDebugDetails * getFeature () noexcept
double getHeadingInDegrees () const noexcept
 return the camera heading in degrees, with respect to Earth
double getPitchInDegrees () const noexcept
 return the camera pitch in degrees, with respect to Earth
double getScale () const noexcept
 Get the map view current scale ( meters for 1 mm ).
bool hasTerrainTopography () const noexcept
 Check if map view contains terrain topography information.
void setWatermarkText (const String &line1, const String &line2, float fScaleFactor=1.0, EWatermarkPosition pos=EWPCenter) noexcept
 Set custom watermark texts to show to the final user.
StrongPointer< ScreengetScreen () const noexcept
 Get the parent screen.
Rect getViewport () const noexcept
 Get view viewport in parent screen coordinates.
RectF getViewportF () const noexcept
 Get screen viewport in parent screen ratio.
bool handleKeyboardEvent (EKey key, EKeyAction action) noexcept
 Handles a keyboard event.
Canvasresize (const RectF &screenRatio) noexcept
 Resize the view.
int captureAsImage (const String &filePath, Rect const &rect=Rect(), EImageFileFormat format=IFF_Jpeg) const noexcept
 Make a screen region capture of the current map in JPEG format.
int captureAsImage (DataBuffer &buffer, Rect const &rect=Rect(), EImageFileFormat format=IFF_Jpeg) const noexcept
 Make a screen region capture of the current map in JPEG format.
Image captureAsImage (Rect const &rect=Rect()) const noexcept
 Make a screen region capture of the current map in JPEG format.
bool isView () const noexcept
 Deprecated.
bool isMapView () const noexcept
 Check if canvas is a MapView object.
void detach () noexcept
 Detach canvas from rendering process.

Static Public Member Functions

static StrongPointer< MapViewproduce (StrongPointer< Screen > screen, const RectF &screenRatio, MapViewListener listener=MapViewListener(), StrongPointer< MapCamera > camera=StrongPointer< MapCamera >())
 Create a view object on the given screen.
static StrongPointer< MapViewproduce (OpenGLContext context, MapViewListener listener=MapViewListener())
 Create a view object in the simplest mode possible.
static StrongPointer< Canvasproduce (StrongPointer< Screen > screen, const RectF &screenRatio, CanvasListener listener) noexcept
 Create a canvas object on the given screen.

Protected Types

using Base = ApiObject<ICanvas, false>
 Base.

Detailed Description

MapView object - displays a map.

MapView supports a wide range of operations like resize, zoom, rotate, animated fly to specific position or select map objects. The map appearance is fully customizable. By using the attached preferences() it is possible to specify for each map what map objects to be visible and when; it is possible to change the colors, widths and other properties of the map objects; or to specify which landmarks should be visible on map. Multiple MapView objects can be created using the same Screen or a different one.

Implements share-read / write Api object over IMapView.

Member Function Documentation

◆ activateHighlight() [1/2]

MapView & gem::MapView::activateHighlight ( const LandmarkList & landmarks,
const HighlightRenderSettings & renderSettings = HighlightRenderSettings(),
short highlightId = 0 )
inlinenoexcept

Enable highlighting for the given landmark list.

Parameters
[in]landmarksLandmark
[in]renderSettingsSpecifies the way the provided landmarks are displayed on the map
[in]highlightIdThe highlighted collection id ( optional ). If a highlighted collection with this id already exists, it will be replaced

Highlighted collections will be displayed in ascending order sorted by highlightId

If functions fails, GEM_ERROR will contain the error

Returns
Reference to the current MapView object.

◆ activateHighlight() [2/2]

MapView & gem::MapView::activateHighlight ( const OverlayItemList & overlays,
const HighlightRenderSettings & renderSettings = HighlightRenderSettings(),
short highlightId = 0 )
inlinenoexcept

Enable the highlighting for the given overlay list.

Parameters
[in]overlaysOverlays
[in]renderSettingsSpecifies the way the provided landmarks are displayed on the map
[in]highlightIdThe highlighted collection id ( optional ). If a highlighted collection with this id already exists, it will be replaced

Highlighted collections will be displayed in ascending order sorted by highlightId

If functions fails, GEM_ERROR will contain the error

Returns
Reference to the current MapView object.

◆ alignNorthUp()

MapView & gem::MapView::alignNorthUp ( Animation animation = Animation())
inline

Set the map north-up oriented.

Parameters
[in]animation
Returns
A reference to the current MapView object, allowing for method chaining.

◆ canZoom()

bool gem::MapView::canZoom ( int zoomLevel,
Xy xy = Xy() )
inlinenoexcept

Check if it is possible to zoom at a specified zoom level.

Parameters
[in]zoomLevelZoom level.
[in]xyScreen coordinates under which map should keep position. The coordinates are relative to the view's parent screen.
Returns
True if the zoom is possible; false if is not possible.

◆ captureAsImage() [1/3]

int gem::Canvas::captureAsImage ( const String & filePath,
Rect const & rect = Rect(),
EImageFileFormat format = IFF_Jpeg ) const
inlinenoexceptinherited

Make a screen region capture of the current map in JPEG format.

No cursor/on-screen info is included.

Parameters
[in]filePathFile path.
[in]rectThe screen rectangle to capture. If ( 0, 0, 0, 0) is provided then the entire map screen is captured.
[in]formatThe image format, default Jpeg
Returns
0 if successful, otherwise an error code

◆ captureAsImage() [2/3]

int gem::Canvas::captureAsImage ( DataBuffer & buffer,
Rect const & rect = Rect(),
EImageFileFormat format = IFF_Jpeg ) const
inlinenoexceptinherited

Make a screen region capture of the current map in JPEG format.

No cursor/on-screen info is included.

Parameters
[in]bufferThe buffer in which the capture is made.
[in]rectThe screen rectangle to capture. If ( 0, 0, 0, 0) is provided then the entire map screen is captured.
[in]formatThe image format, default Jpeg
Returns
0 if successful, otherwise an error code

◆ captureAsImage() [3/3]

Image gem::Canvas::captureAsImage ( Rect const & rect = Rect()) const
inlinenoexceptinherited

Make a screen region capture of the current map in JPEG format.

No cursor/on-screen info is included.

Parameters
[in]rectThe screen rectangle to capture. If ( 0, 0, 0, 0) is provided then the entire map screen is captured.
Returns
The captured image

◆ centerOnArea() [1/2]

MapView & gem::MapView::centerOnArea ( const GeographicArea & area,
int zoomLevel,
Rect viewRectangle,
Animation animation = Animation() )
inlinenoexcept

Center the on the given WGS area.

Parameters
[in]areaGeographic area
[in]zoomLevelZoom level. When -1 is used, the zoom level is automatically selected so that the entire area is visible on the map.
[in]viewRectangleRectangle portion of the view where area should be centered. The coordinates are relative to view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnArea() [2/2]

MapView & gem::MapView::centerOnArea ( const GeographicArea & area,
int zoomLevel = -1,
Xy xy = Xy(),
Animation animation = Animation() )
inlinenoexcept

Center the on the given WGS area.

Parameters
[in]areaGeographic area
[in]zoomLevelZoom level. When -1 is used, the zoom level is automatically selected so that the entire area is visible on the map.
[in]xyScreen coordinate where area should be centered. The coordinates are relative to the view's parent screen.
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnCoordinates() [1/2]

MapView & gem::MapView::centerOnCoordinates ( const Coordinates & coords,
Animation animation )
inlinenoexcept

Center the WGS coordinates on screen coordinates with animation.

Parameters
[in]coordsCoordinates
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnCoordinates() [2/2]

MapView & gem::MapView::centerOnCoordinates ( const Coordinates & coords,
int zoomLevel = -1,
Xy xy = Xy(),
Animation animation = Animation(),
double mapAngle = (std::numeric_limits<double>::max)(),
double viewAngle = (std::numeric_limits<double>::max)() )
inlinenoexcept

Center the WGS coordinates on screen coordinates.

Parameters
[in]coordsCoordinates
[in]zoomLevelZoom level (Use -1 for automatic selection)
[in]xyScreen position where the coordinates should project ( default uses the specified cursor coordinates ). The coordinates are relative to the view's parent screen.
[in]animationSpecifies the animation to be used by the operation.
[in]mapAngleMap rotation angle in the range [0.0, 360.0] degrees (Use std::numeric_limits<double>::max() for automatic selection).
[in]viewAngleMapView angle in the range [-90.0, 90.0] degrees (Use std::numeric_limits<double>::max() for automatic selection).
Returns
Reference to the current MapView object.

◆ centerOnLocation()

MapView & gem::MapView::centerOnLocation ( const Landmark & location,
Rect viewRectangle = Rect(),
Animation animation = Animation() )
inlinenoexcept

Center on the given landmark location.

Parameters
[in]locationLandmark location
[in]viewRectangleRectangle portion of the view where location should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.
[in]animationSpecifies the animation to be used by the operation.

The best location presentation will be selected:

if location has a contour, a center on contour area will be done, otherwise a center on location coordinates

Returns
Reference to the current MapView object.

◆ centerOnMapRoutes()

MapView & gem::MapView::centerOnMapRoutes ( ERouteDisplayMode displayMode = RDM_Full,
const Rect & viewRectangle = Rect(),
Animation animation = Animation() )
inlinenoexcept

Center on the existing routes collection.

The zoom level is automatically selected.

Parameters
[in]displayModeRoute display mode
[in]viewRectangleRectangle portion of the view where routes should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.

Leave empty to allow SDK to compute an optimal viewport

Use getOptimalRoutesCenterViewport to adjust a custom viewport for optimal routes presentation

Parameters
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnRoute() [1/2]

MapView & gem::MapView::centerOnRoute ( const Route & route,
int startDist,
int endDist,
Rect viewRectangle = Rect(),
Animation animation = Animation() )
inlinenoexcept

Center On the given route parts.

The zoom level is automatically selected so that the entire route part between start distance and end distance is visible on the map

Parameters
[in]routeRoute to be shown.
[in]startDiststart distance from route begin
[in]endDistend distance from route begin
[in]viewRectangleRectangle portion of the view where route should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.

Leave empty to allow SDK to compute an optimal viewport

Use getOptimalRoutesCenterViewport to adjust a custom viewport for optimal routes presentation

Parameters
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnRoute() [2/2]

MapView & gem::MapView::centerOnRoute ( const Route & route,
Rect viewRectangle = Rect(),
Animation animation = Animation() )
inlinenoexcept

Center on the given route.

The zoom level is automatically selected so that the entire route is visible on the map.

Parameters
[in]routeRoute to be shown.
[in]viewRectangleRectangle portion of the view where route should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnRouteInstruction()

MapView & gem::MapView::centerOnRouteInstruction ( const RouteInstruction & instruction,
int zoomLevel = -1,
Xy xy = Xy(),
Animation animation = Animation(),
double viewAngle = (std::numeric_limits<double>::max)() )
inlinenoexcept

Center on the given route instruction and displays the associated turn arrow in the map view.

The route instruction turn arrow is visible on map.

Parameters
[in]instructionRouting instruction. If RouteInstruction is not valid ( e.g. a default object ) then the previous displayed turn arrow is erased
[in]zoomLevelZoom level (Use -1 for automatic selection)
[in]xyScreen coordinate where area should be centered. The coordinates are relative to the view's parent screen.
[in]animationSpecifies the animation to be used by the operation.
[in]viewAngleSpecifies the map pitch angle
Returns
Reference to the current MapView object.

◆ centerOnRoutes()

MapView & gem::MapView::centerOnRoutes ( const RouteList & routesList,
ERouteDisplayMode displayMode = RDM_Full,
const Rect & viewRectangle = Rect(),
Animation animation = Animation() )
inlinenoexcept

Center on the given routes collection.

Routes from the list WILL NOT be visible on the map. They must be added to preferences().routes() prior to this call. The zoom level is automatically selected.

Parameters
[in]routesListRoute list to be centered on.
[in]displayModeRoute display mode
[in]viewRectangleRectangle portion of the view where routes should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.

Leave empty to allow SDK to compute an optimal viewport

Use getOptimalRoutesCenterViewport to adjust a custom viewport for optimal routes presentation

Parameters
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ centerOnRouteTrafficEvent()

MapView & gem::MapView::centerOnRouteTrafficEvent ( const RouteTrafficEvent & traffic,
int zoomLevel = -1,
Rect viewRectangle = Rect(),
Animation animation = Animation(),
double viewAngle = (std::numeric_limits<double>::max)() )
inlinenoexcept

Center on the given traffic event.

Parameters
[in]trafficRoute traffic event
[in]zoomLevelZoom level (Use -1 for automatic selection)
[in]viewRectangleRectangle portion of the view where route traffic event should be centered. The coordinates are relative to the view's parent screen. If rectangle exceeds view's viewport, it will be clipped to fit into it.
[in]animationSpecifies the animation to be used by the operation.
[in]viewAngleSpecifies the map pitch angle
Returns
Reference to the current MapView object.

◆ checkObjectVisibility()

bool gem::MapView::checkObjectVisibility ( const MapSceneObject & obj,
Rect viewport = Rect() ) const
inlinenoexcept

Check if the given scene object visible in the given viewport.

Parameters
[in]objThe scene object to test
[in]viewportViewport rectangle in screen coordinates. If no viewport is given, the whole screen is used
Returns
True if the object is visible within the viewport, false otherwise.

◆ cursorSelectionLandmarks()

const LandmarkListRef gem::MapView::cursorSelectionLandmarks ( ) const
inlinenoexcept

Retrieves a reference to a list of landmarks under the current cursor location.

This method returns a list of landmarks that are directly beneath the cursor on the map. It can be used to identify landmarks that a user might be pointing to or interested in.

Returns
A reference to a list of Landmark objects under the cursor. If no landmarks are found, the list will be empty.

◆ cursorSelectionMarkers()

const MarkerMatchListRef gem::MapView::cursorSelectionMarkers ( ) const
inlinenoexcept

Retrieves a reference to a list of markers under the current cursor location.

Markers are typically used to indicate specific points of interest on the map. This method allows for identifying which markers, if any, are under the cursor, enabling interactions such as displaying additional information about the marker.

Returns
A reference to a list of MarkerMatch objects under the cursor. If no markers are found, the list will be empty.

◆ cursorSelectionOverlayItems()

const OverlayItemListRef gem::MapView::cursorSelectionOverlayItems ( ) const
inlinenoexcept

Retrieves a reference to a list of overlay items under the current cursor location.

Overlay items can include various custom or additional map elements added on top of the base map layer. This method allows for the detection and interaction with these elements based on cursor position.

Returns
A reference to a list of OverlayItem objects under the cursor. If no overlay items are found, the list will be empty.

◆ cursorSelectionPath()

const PathRef gem::MapView::cursorSelectionPath ( ) const
inlinenoexcept

Retrieves the path under the current cursor location.

Paths can represent routes, trails, or other linear features on the map. This method identifies the path that is directly beneath the cursor, allowing for interactions such as path selection or displaying path details.

Returns
A reference to the Path object under the cursor. If no path is found, this will be a null reference.

◆ cursorSelectionRoutes()

const RouteListRef gem::MapView::cursorSelectionRoutes ( ) const
inlinenoexcept

Retrieves a reference to a list of routes under the current cursor location.

This method is used to determine which routes, if any, are under the cursor's current map position. It's particularly useful for route planning and navigation applications where users may need to select or interact with specific routes.

Returns
A reference to a list of Route objects under the cursor. If no routes are found, the list will be empty.

◆ cursorSelectionSceneObject()

StrongPointer< MapSceneObject > gem::MapView::cursorSelectionSceneObject ( ) const
inlinenoexcept

Retrieves the scene object under the current cursor selection.

Scene objects can include 3D models, custom drawings, or other complex visual elements added to the map. This method determines which scene object, if any, is under the cursor, facilitating interactions like selection or manipulation.

Returns
A strong pointer to the MapSceneObject under the cursor. If no scene object is found, this will return an empty pointer.

◆ cursorSelectionStreets()

const LandmarkListRef gem::MapView::cursorSelectionStreets ( ) const
inlinenoexcept

Retrieves a reference to a list of streets under the current cursor location.

This method provides information about streets located directly under the cursor on the map. Useful for applications that require the user to select or identify streets.

Returns
A reference to a list of Street objects under the cursor. If no streets are found, the list will be empty.

◆ cursorSelectionTrafficEvents()

const TrafficEventListRef gem::MapView::cursorSelectionTrafficEvents ( ) const
inlinenoexcept

Retrieves a reference to a list of traffic events under the current cursor location.

Traffic events can include incidents like accidents, roadworks, or traffic jams. This method is useful for applications that provide real-time traffic information and require user interaction with traffic events.

Returns
A reference to a list of TrafficEvent objects under the cursor. If no traffic events are found, the list will be empty.

◆ deactivateAllHighlights()

MapView & gem::MapView::deactivateAllHighlights ( )
inlinenoexcept

Disable all highlights.

If functions fails, GEM_ERROR will contain the error

Returns
Reference to the current MapView object.

◆ deactivateHighlight()

MapView & gem::MapView::deactivateHighlight ( short highlightId = 0)
inlinenoexcept

Disable highlighting.

Parameters
[in]highlightIdThe highlighted collection id ( optional )

If functions fails, GEM_ERROR will contain the error ( e.g. error::KInvalidInput if given highlightId doesn't exist )

Returns
Reference to the current MapView object.

◆ detach()

void gem::Canvas::detach ( )
inlinenoexceptinherited

Detach canvas from rendering process.

If OpenGL context is not available anymore during canvas destruction, this method should be called when the context is still valid in order to do all needed cleanups

◆ extensions()

MapViewExtensionsRef gem::MapView::extensions ( )
inlinenoexcept

Get access to MapViewExtensions.

Returns
A reference to the MapViewExtensions object, providing additional functionalities and extensions specific to the MapView.

◆ features()

IMapDebugDetails * gem::MapView::features ( )
inlinenoexcept

Obtain the map view features object.

Returns
A pointer to the map view features ( experimental )

◆ fling()

MapView & gem::MapView::fling ( float velocityX,
float velocityY )
inlinenoexcept

Fling / swipe map.

Parameters
[in]velocityXHorizontal velocity in screen units

A positive value will move the map to the screen right, a negative value will move the map to the screen left

Parameters
[in]velocityYVertical velocity in screen units

A positive value will move the map to the screen bottom, a negative value will move the map to the screen top

Returns
A reference to the current MapView object, allowing for method chaining.

◆ getAltitude()

double gem::MapView::getAltitude ( const Coordinates & coords) const
inlinenoexcept

Get altitude at the given coordinates.

Parameters
[in]coordsWGS Coordinates
Returns
Altitude as meters from sea level if capability exist, otherwise returns 0

Use hasTerrainTopography() to check if the map view has the capability to return an altitude at coordinates

◆ getCamera()

StrongPointer< MapCamera > gem::MapView::getCamera ( ) const
inlinenoexcept

Retrieves the camera associated with this MapView.

Returns
A strong pointer to the MapCamera used by this view.

◆ getCursorScreenPosition()

Xy gem::MapView::getCursorScreenPosition ( ) const
inlinenoexcept

Get the cursor screen position.

The coordinates are relative to the view's parent screen.

Returns
The current screen coordinates (Xy) of the cursor, relative to the view's parent screen.

◆ getCursorWgsPosition()

Coordinates gem::MapView::getCursorWgsPosition ( ) const
inlinenoexcept

Get the cursor WGS coordinates.

Returns
cursor coords

◆ getFeature()

IMapDebugDetails * gem::MapView::getFeature ( )
inlinenoexcept
Deprecated
use features() instead
Returns
A pointer to the map view features

◆ getHeadingInDegrees()

double gem::MapView::getHeadingInDegrees ( ) const
inlinenoexcept

return the camera heading in degrees, with respect to Earth

Returns
The heading angle of the camera in degrees, where 0 degrees indicates north.

◆ getHighlight()

LandmarkList gem::MapView::getHighlight ( int highlightId) const
inlinenoexcept

Get highlighted geographic area.

Parameters
[in]highlightIdAn identifier for the highlight
Returns
A LandmarkList containing all landmarks within the highlighted area.

◆ getHighlightArea()

RectangleGeographicArea gem::MapView::getHighlightArea ( int highlightId = 0) const
inlinenoexcept

Get highlighted geographic area.

Parameters
[in]highlightIdAn identifier for the highlight whose area is to be retrieved, with a default value of 0.
Returns
A RectangleGeographicArea object representing the geographic bounds of the highlighted area.

◆ getMaxSlippyZoomLevel()

double gem::MapView::getMaxSlippyZoomLevel ( ) const
inlinenoexcept

Get the maximum slippy zoom level.

Bigger zoom factor means closer to the map.

Returns
The maximum slippy zoom level as a double.

◆ getMaxZoomLevel()

int gem::MapView::getMaxZoomLevel ( ) const
inlinenoexcept

Get the configured max zoom level.

Returns
The minimum zoom level configured for the map view.

◆ getMinZoomLevel()

int gem::MapView::getMinZoomLevel ( ) const
inlinenoexcept

Get the configured min zoom level.

Returns
The minimum zoom level configured for the map view.

◆ getNearestLocations()

LandmarkList gem::MapView::getNearestLocations ( const Coordinates & coordinates,
const IntList & lmkStores = {},
int radius = 0 ) const
inlinenoexcept

Retrieve the set of landmarks on the specified coordinates.

This is a quick synchronous reverse geocoding method.

Parameters
[in]coordinatesCoordinates
[in]lmkStoresA list of landmark store types where to search for locations, see ELandmarkStoreType.

Supported landmark stores are LST_MapAddress, LST_MapPoi, LST_MapCity, LST_MapRoads

If empty, all supported landmark stores will be searched

Parameters
[in]radiusThe search radius in meters, If 0, an optimal default value will be internally used
Returns
A LandmarkList containing the nearest locations to the specified coordinates. If no landmarks are found, the list will be empty.

◆ getOptimalHighlightCenterViewport()

Rect gem::MapView::getOptimalHighlightCenterViewport ( const Rect & viewRectangle = Rect()) const
inlinenoexcept

Gets the optimal highlight center viewport given the user custom input.

The returned viewport is adjusted so all highlight information will be visible

User can use this as input to centerOnArea viewRectangle parameter

Parameters
[in]viewRectangleRectangle portion of the view where highlight should be centered. If empty, the whole viewport is used. If rectangle exceeds view's viewport, it will be clipped to fit into it.
Returns
The adjusted viewport. The coordinates are relative to the view's parent screen.

◆ getOptimalRoutesCenterViewport()

Rect gem::MapView::getOptimalRoutesCenterViewport ( const RouteList & routesList,
const Rect & viewRectangle = Rect() ) const
inlinenoexcept

Gets the highlighted items optimal center viewport given the user custom input.

The returned viewport is adjusted so all highlighted information will be visible

User can use this as input to centerOnArea viewRectangle parameter

Parameters
[in]routesListRoute list to be shown.
[in]viewRectangleRectangle portion of the view where routes should be centered. If empty, the whole viewport is used. If rectangle exceeds view's viewport, it will be clipped to fit into it.
Returns
The adjusted viewport. The coordinates are relative to the view's parent screen.

◆ getPitchInDegrees()

double gem::MapView::getPitchInDegrees ( ) const
inlinenoexcept

return the camera pitch in degrees, with respect to Earth

Returns
The pitch angle of the camera in degrees

◆ getScale()

double gem::MapView::getScale ( ) const
inlinenoexcept

Get the map view current scale ( meters for 1 mm ).

Returns
The scale of the map view

◆ getScreen()

StrongPointer< Screen > gem::Canvas::getScreen ( ) const
inlinenoexceptinherited

Get the parent screen.

Returns
The parent screen

◆ getSlippyZoomLevel()

double gem::MapView::getSlippyZoomLevel ( ) const
inlinenoexcept

Get slippy zoom level.

Returns
The current slippy zoom level

◆ getStyleLayerInfo()

StyleLayerInfoList gem::MapView::getStyleLayerInfo ( const Coordinates & coords) const
inlinenoexcept

Get style layers information at the given coordinates.

Parameters
[in]coordsThe geographic coordinates where style layer information is requested.
Returns
A list of StyleLayerInfo objects for the specified coordinates.

◆ getStyleLegend()

StyleLegendList gem::MapView::getStyleLegend ( ) const
inlinenoexcept

Get style legend list ( for layers which have legends ).

Returns
A list of StyleLegend objects

◆ getTransferStatistics()

TransferStatisticsRef gem::MapView::getTransferStatistics ( EViewOnlineServiceType serviceType) const
inlinenoexcept

Get data transfer statistics for a given service.

Parameters
[in]serviceTypeThe type of the online service for which data transfer statistics are requested.
Returns
A reference to the TransferStatistics object containing data transfer information for the specified service.

◆ getViewport()

Rect gem::Canvas::getViewport ( ) const
inlinenoexceptinherited

Get view viewport in parent screen coordinates.

origin is always 0, 0

Returns
The view viewport

◆ getViewportF()

RectF gem::Canvas::getViewportF ( ) const
inlinenoexceptinherited

Get screen viewport in parent screen ratio.

origin is always 0, 0

Returns
The view viewport

◆ getVisibleRouteInterval()

std::pair< int, int > gem::MapView::getVisibleRouteInterval ( const Route & route,
Rect clipRect = Rect() ) const
inlinenoexcept

Get the clipped part of the given route as a pair (startDistance, endDistance).

Parameters
[in]routeTarget route
[in]clipRectClipping rectangle in screen coordinates. If no clip rectangle is given, the whole screen is used
Returns
A pair of integers representing the start and end distances of the visible portion of the route.

◆ getZoomLevel()

int gem::MapView::getZoomLevel ( ) const
inlinenoexcept

Get zoom level.

Returns
The current zoom level

◆ handleKeyboardEvent()

bool gem::Canvas::handleKeyboardEvent ( EKey key,
EKeyAction action )
inlinenoexceptinherited

Handles a keyboard event.

Parameters
keyType of key that was interacted with.
actionType of action that was performed on key.
Returns
True if the canvas used the key action, in which case the UI should stop forwarding the key to other UI elements

◆ hasTerrainTopography()

bool gem::MapView::hasTerrainTopography ( ) const
inlinenoexcept

Check if map view contains terrain topography information.

If true, transformScreenToWgs() function returns coordinates with terrain altitude set

The map view has terrain topography if the map style includes the terrain elevation layer and data is available on queried location

Returns
True if the map view contains terrain topography information, false otherwise.

◆ highlightHoveredMapLabel()

int gem::MapView::highlightHoveredMapLabel ( const Xy & pt,
bool selectMapObjects ) const
inlinenoexcept

Highlight the hovered map label under the given screen coordinates.

Parameters
[in]ptThe hovered screen point

To turn off the hover highlight call the function with (0, 0) screen position

Parameters
[in]selectMapObjects

If true and a label is hovered, map objects attached to label are returned via IMapViewListener::onHoveredMapLabelHighlighted

If false, no call to IMapViewListener::onHoveredMapLabelHighlighted is issued

Returns
The operation error code

Returns error::KNotFound if no label was found

A recommended implementation is to call highlightHoveredMapLabel ( ..., selectMapObjects = false ) in order to check if a label is hovered ( and eventually update tracking device cursor shape etc ) and if the cursor position is stationary for a reasonable time period ( e.g. 500 ms ) call highlightHoveredMapLabel( ..., selectMapObjects = true ) to retrieve the hovered map object data

◆ isAnimationInProgress()

bool gem::MapView::isAnimationInProgress ( ) const
inlinenoexcept

Check if there is an animation in progress.

Returns
True if an animation is running; false otherwise.

◆ isCameraMoving()

bool gem::MapView::isCameraMoving ( ) const
inlinenoexcept

Check if view camera is moving.

Returns
True if the camera is moving, false otherwise.

◆ isDefaultFollowingPosition()

bool gem::MapView::isDefaultFollowingPosition ( ) const
inlinenoexcept

Test if following the current position is in default auto-zoom mode.

Returns
True if the map is in the default auto-zoom follow position mode, false if it has been manually adjusted or is not in follow position mode.

◆ isFollowingPosition()

bool gem::MapView::isFollowingPosition ( bool bAlsoFlyToPosition = true) const
inlinenoexcept

Test if following the current position mode.

Parameters
[in]bAlsoFlyToPositionIf true, considers the map to be in follow position mode even when animating towards a position ("flying"). If false, the map is considered to be in follow position mode only when it is actively tracking the current position without any ongoing animation.
Returns
True if the map is currently following the current position

◆ isFollowingPositionTouchHandlerModified()

bool gem::MapView::isFollowingPositionTouchHandlerModified ( ) const
inlinenoexcept

Test if following the current position is modified by the touch handler.

In this mode, the camera follows the position tracker from a fixed relative position manually adjusted / set by the user using touch input

Returns
True if the follow position mode has been manually adjusted by the user, false if it remains in its default state.

◆ isMapView()

bool gem::Canvas::isMapView ( ) const
inlinenoexceptinherited

Check if canvas is a MapView object.

Returns
True if the canvas is a MapView object

◆ isView()

bool gem::Canvas::isView ( ) const
inlinenoexceptinherited

Deprecated.

Deprecated
Replaced by isMapView.
Returns
True if the canvas is a view

◆ maxZoomLevel()

int gem::MapView::maxZoomLevel ( ) const
inlinenoexcept

Get the maximum zoom level.

Bigger zoom factor means closer to the map.

Returns
The maximum zoom level as an integer.

◆ preferences()

MapViewPreferencesRef gem::MapView::preferences ( )
inlinenoexcept

Get access to this view preferences.

Returns
A reference to the MapViewPreferences object associated with this view.

◆ produce() [1/3]

StrongPointer< Canvas > gem::Canvas::produce ( StrongPointer< Screen > screen,
const RectF & screenRatio,
CanvasListener listener )
inlinestaticnoexceptinherited

Create a canvas object on the given screen.

Parameters
[in]screenThe view's parent screen (reference to it held internally)
[in]screenRatioThe viewport expressed in parent screen ratio
[in]listenerThe canvas listener
Returns
The canvas object

◆ produce() [2/3]

StrongPointer< MapView > gem::MapView::produce ( OpenGLContext context,
MapViewListener listener = MapViewListener() )
inlinestatic

Create a view object in the simplest mode possible.

Note
Internally a default camera is created and a default screen with automatic rendering rule.
Parameters
[in]contextThe view's OpenGL context
[in]listenerThe view listener
Returns
A StrongPointer to the newly created MapView object, configured to use the provided OpenGL context and listener.

◆ produce() [3/3]

StrongPointer< MapView > gem::MapView::produce ( StrongPointer< Screen > screen,
const RectF & screenRatio,
MapViewListener listener = MapViewListener(),
StrongPointer< MapCamera > camera = StrongPointer<MapCamera>() )
inlinestatic

Create a view object on the given screen.

Parameters
[in]screenThe view's parent screen (reference to it held internally)
[in]screenRatioThe viewport expressed in parent screen ratio
[in]listenerThe view listener
[in]cameraThe camera for the view, if not given, one is created and assigned to it (reference to it held internally)
Returns
A StrongPointer to the newly created MapView object

◆ resize()

Canvas & gem::Canvas::resize ( const RectF & screenRatio)
inlinenoexceptinherited

Resize the view.

Parameters
[in]screenRatioThe new viewport expressed in parent screen ratio
Returns
The view object

◆ restoreFollowingPosition()

MapView & gem::MapView::restoreFollowingPosition ( Animation animation = Animation())
inlinenoexcept

Restore following position from a manually adjusted mode to default auto-zoom mode.

Parameters
[in]animationSpecifies the animation to be used by the operation.
Returns
Reference to the current MapView object.

◆ scroll()

MapView & gem::MapView::scroll ( float dx,
float dy )
inlinenoexcept

Scroll map.

Parameters
[in]dxHorizontal dx in screen units

A positive value will move the map to the screen right, a negative value will move the map to the screen left

Parameters
[in]dyVertical dy in screen units

A positive value will move the map to the screen bottom, a negative value will move the map to the screen top

Returns
A reference to the current MapView object, allowing for method chaining.

◆ setCamera()

MapView & gem::MapView::setCamera ( StrongPointer< MapCamera > camera)
inlinenoexcept

Set the given camera.

Parameters
cameraA strong pointer to the new MapCamera to be used.
Returns
Reference to the current MapView object.

◆ setClippingArea()

MapView & gem::MapView::setClippingArea ( const RectF & area)
inlinenoexcept

Sets the view clipping rectangle in parent screen ratio.

Parameters
[in]areaThe clipping rectangle to set, expressed as a fraction of the parent screen's size (for example, 0.5 for half the screen's width or height). This rectangle defines the visible portion of the MapView.

To reset the clipping area to whole view area call setClippingArea( getViewportF() )

Returns
A reference to the current MapView object, allowing for method chaining.

◆ setCursorScreenPosition()

MapView & gem::MapView::setCursorScreenPosition ( Xy xy)
inlinenoexcept

Set the cursor screen position.

Parameters
[in]xyPosition relative to parent screen. The coordinates are relative to the view's parent screen.

Use this function to trigger a map view selection ( Poi, landmark, overlay, route, path, marker ) at the given screen coordinates

If map view selection changes, a notification is sent via IMapViewListener::onCursorSelectionUpdated

The current view selection can be queried via cursorSelection... () functions

Returns
A reference to the current MapView object, allowing for method chaining.

◆ setMaxZoomLevel()

void gem::MapView::setMaxZoomLevel ( int zl)
inlinenoexcept

Set the configured max zoom level.

Parameters
[in]zlThe maximum zoom level to be set.

◆ setMinZoomLevel()

void gem::MapView::setMinZoomLevel ( int zl)
inlinenoexcept

Set the configured min zoom level.

Parameters
[in]zlThe minimum zoom level to be set.

◆ setSlippyZoomLevel()

double gem::MapView::setSlippyZoomLevel ( double zoomLevel,
int duration = 0,
Xy xy = Xy() )
inlinenoexcept

Set a new zoom level based on slippy tile level.

When "follow position" is active, the current position will be used as the reference point for the operation. Otherwise, the screen center will be used. This may be between 0 and MaxSlippyZoomLevel().

Parameters
[in]zoomLevelSlippy Zoom level
[in]durationThe animation duration in milliseconds (0 means no animation)
[in]xyScreen coordinates under which map should keep position. The coordinates are relative to the view's parent screen.
Returns
The previous zoom level

◆ setWatermarkText()

void gem::MapView::setWatermarkText ( const String & line1,
const String & line2,
float fScaleFactor = 1.0,
EWatermarkPosition pos = EWPCenter )
inlinenoexcept

Set custom watermark texts to show to the final user.

Parameters
[in]line1The first line to show
[in]line2The second line to show - this rrai a smaller font
[in]fScaleFactorThe scale factor
[in]posThe watermark position

◆ setZoomLevel()

int gem::MapView::setZoomLevel ( int zoomLevel,
int duration = 0,
Xy xy = Xy() )
inlinenoexcept

Set a new zoom level centered on the specified screen position.

This may be between 0 and getMaxZoomLevel().

Parameters
[in]zoomLevelZoom level.
[in]durationThe animation duration in milliseconds (0 means no animation)
[in]xyScreen coordinates under which map should keep position. The coordinates are relative to the view's parent screen.
Returns
On success, the previous zoom level. On error, the error code

◆ skipAnimation()

MapView & gem::MapView::skipAnimation ( bool bJumpToDestination = true)
inlinenoexcept

Stop the current animation.

When this will be finished the animation will be completed with error code error::KCancel.

Parameters
[in]bJumpToDestination- true if we want to jump to the destination when stopping animation; otherwise stop immediately
Returns
Reference to the current MapView object.

◆ startFollowingPosition()

MapView & gem::MapView::startFollowingPosition ( Animation animation = Animation(),
int zoomLevel = -1,
double viewAngle = (std::numeric_limits<double>::max)(),
StrongPointer< MapSceneObject > positionObj = StrongPointer<MapSceneObject>(),
CameraTrackMethod trackMethod = CameraTrackMethod() )
inlinenoexcept

Start following the current position.

Requires automatic map rendering. Disables the cursor if enabled.

Parameters
[in]animationSpecifies the animation to be used by the operation.
[in]zoomLevelZoom level where the animation stops( Use -1 for automatic selection)
[in]viewAngleMap view angle ( see setViewAngle ). Default is std::numeric_limits<double>::max() meaning use default specified
[in]positionObjthe reference object to follow.
[in]trackMethodTrack Mode
Returns
Reference to the current MapView object.

◆ stopFollowingPosition()

MapView & gem::MapView::stopFollowingPosition ( bool restoreCameraMode = false)
inlinenoexcept

Stop following the current position.

Parameters
[in]restoreCameraModeRestore default camera zoom level and view angle in follow position mode
Returns
Reference to the current MapView object.

◆ transformScreenToWgs() [1/2]

RectangleGeographicAreaList gem::MapView::transformScreenToWgs ( Rect const & rectangle) const
inlinenoexcept

Converts a screen rectangle to WGS areas list.

Parameters
[in]rectangleScreen rectangle. The input rectangle will be clipped against viewport.

If default empty provided, the whole viewport is transformed

Returns
WGS84 areas list

◆ transformScreenToWgs() [2/2]

Coordinates gem::MapView::transformScreenToWgs ( Xy xy) const
inlinenoexcept

Convert a screen coordinate to a WGS coordinate.

Parameters
[in]xyScreen coord. The coordinates are relative to the view's parent screen.
Returns
WGS384 coords

◆ transformWgsToScreen()

Xy gem::MapView::transformWgsToScreen ( const Coordinates & coords) const
inlinenoexcept

Convert a WGS84 coordinate to a screen coordinate.

Parameters
[in]coordsWGS Coordinates
Returns
The screen coordinates relative to view parent screen