GemMapController class Maps & 3D Scenes
Controller for a single GemMap instance running on the host platform.
Obtain an instance from the GemMap.onMapCreated callback; do not construct
this class directly. The controller exposes
camera control, coordinate transforms, highlighting,
marker and overlay integration, map capture, and follow-position behavior.
Typical uses include programmatic camera manipulation, persisting or restoring view state, driving custom overlays, and reacting to interaction events such as touches, gestures, hover selections, and render or resize notifications. Use preferences for map configuration and extensions for optional feature access.
See also:
- GemMap – Widget that owns the controller lifecycle.
- MapCamera – Camera controller available via camera.
- FollowPositionPreferences – Configure follow-position behavior.
- MapViewPreferences – Customize rendering and interaction options.
Properties
- camera ↔ MapCamera
-
Retrieves the current map camera for advanced positioning and orientation control.
getter/setter pairinherited
-
cursorScreenPosition
→ Point<
int> -
Retrieves the cursor's current position in screen coordinates.
no setterinherited
- cursorWgsPosition → Coordinates
-
Retrieves the cursor's current position in WGS84 geographic coordinates.
no setterinherited
- devicePixelSize → double
-
The number of device pixels represented by each logical Flutter pixel.
no setter
- extensions → MapViewExtensions
-
Retrieves the map view extensions for additional functionality.
no setterinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
- hasTerrainTopography → bool
-
Check if map view contains terrain topography information
no setterinherited
- isAnimationInProgress → bool
-
Checks whether a map animation is currently in progress.
no setterinherited
- isCameraMoving → bool
-
Checks whether the map camera is currently moving.
no setterinherited
- isFollowingPosition → bool
-
Checks if the camera is actively following the current position.
no setterinherited
- isRenderEnabled ↔ bool
-
Checks if map rendering is currently enabled.
getter/setter pairinherited
- mapAngle → double
-
Map rotation angle in degrees.
no setterinherited
- mapId → int
-
no setterinherited
- maxSlippyZoomLevel → double
-
Retrieves the maximum slippy tile zoom level for the map view.
no setterinherited
- maxZoomLevel ↔ int
-
Retrieves the maximum configured zoom level for the map view.
getter/setter pairinherited
- minZoomLevel ↔ int
-
Retrieves the minimum configured zoom level for the map view.
getter/setter pairinherited
- pointerId → dynamic
-
no setterinherited
- preferences → MapViewPreferences
-
Retrieves the map view's customization preferences.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- scale → double
-
Current map view scale expressed as meters per millimeter on screen.
no setterinherited
- slippyZoomLevel → double
-
Retrieves the current slippy tile zoom level of the map view.
no setterinherited
- viewAngle → double
-
Returns the camera's pitch (view angle) in degrees.
no setterinherited
-
viewport
→ Rectangle<
int> -
Retrieves the current viewport dimensions in physical pixels.
no setterinherited
-
viewportCenter
→ Point<
int> -
Calculates the center point of the current viewport.
no setterinherited
-
viewportF
→ Rectangle<
double> -
Retrieves the current viewport dimensions as ratios relative to the parent screen.
no setterinherited
- zoomLevel → int
-
Retrieves the current zoom level of the map view.
no setterinherited
Methods
-
activateHighlight(
List< Landmark> landmarks, {HighlightRenderSettings? renderSettings, int highlightId = 0}) → void -
Activates highlighting for a collection of landmarks with custom rendering.
inherited
-
activateHighlightOverlayItems(
List< OverlayItem> overlayItems, {HighlightRenderSettings? renderSettings, int highlightId = 0}) → void -
Activates highlighting for a collection of overlay items with custom rendering.
inherited
-
addGeoJsonAsMarkerCollection(
String buffer, String name) → List< MarkerCollection> -
Imports a GeoJSON data buffer as a MarkerCollection list.
inherited
-
alignNorthUp(
{GemAnimation? animation}) → void -
Aligns the map to north-up orientation.
inherited
-
canZoom(
int zoomLevel, {Point< int> ? screenPosition}) → bool -
Checks if zooming to a specified level is possible.
inherited
-
captureImage(
) → Future< Uint8List?> -
Make a screen region capture of the current map in JPEG format.
inherited
-
centerOnArea(
RectangleGeographicArea area, {int zoomLevel = -1, Point< int> ? screenPosition, GemAnimation? animation}) → void -
Centers the map view on a specified geographic area rectangle.
inherited
-
centerOnAreaRect(
RectangleGeographicArea area, {required Rectangle< int> viewRc, int zoomLevel = -1, GemAnimation? animation}) → void -
Centers a geographic area within a specified screen rectangle region.
inherited
-
centerOnCoordinates(
Coordinates coords, {int zoomLevel = -1, Point< int> ? screenPosition, GemAnimation? animation, double? mapAngle, double? viewAngle, double slippyZoomLevel = -1.0}) → void -
Centers the map view on specified WGS84 geographic coordinates.
inherited
-
centerOnMapRoutes(
{RouteDisplayMode? displayMode, Rectangle< int> ? screenRect, GemAnimation? animation}) → void -
Centers the map on all routes currently visible in the MapViewRoutesCollection.
inherited
-
centerOnRoute(
Route route, {Rectangle< int> ? screenRect, GemAnimation? animation}) → void -
Centers the map view on an entire route with automatic zoom adjustment.
inherited
-
centerOnRouteInstruction(
RouteInstruction routeInstruction, {double zoomLevel = -1, Point< int> screenPosition = const Point<int>(0, 0), double? viewAngle, GemAnimation? animation}) → void -
Centers the map on a specific route instruction with visual indicator.
inherited
-
centerOnRoutePart(
Route route, int startDist, int endDist, {Rectangle< int> ? screenRect, GemAnimation? animation}) → void -
Centers the map view on a specific segment of a route with automatic zoom.
inherited
-
centerOnRoutes(
{List< Route> ? routes, RouteDisplayMode displayMode = RouteDisplayMode.full, Rectangle<int> ? screenRect, GemAnimation? animation}) → void -
Centers the map on multiple routes simultaneously with automatic zoom.
inherited
-
centerOnRouteTrafficEvent(
RouteTrafficEvent routeTrafficEvent, {double zoomLevel = -1, Rectangle< int> rectangle = const Rectangle<int>(0, 0, 0, 0), double? viewAngle, GemAnimation? animation}) → void -
Centers the map on a traffic event along a route.
inherited
-
checkObjectVisibility(
{MapSceneObject? mapSceneObject, Rectangle< int> ? rect}) → bool -
Checks if a map scene object is visible within a specified viewport rectangle.
inherited
-
clearRouteInstruction(
) → void -
Removes the route instruction highlight created by centerOnRouteInstruction.
inherited
-
cursorSelectionLandmarks(
) → List< Landmark> -
Retrieve the list of landmarks under the cursor location.
inherited
-
cursorSelectionMapSceneObject(
) → MapSceneObject? -
Retrieves the scene object under the current cursor selection
inherited
-
cursorSelectionMarkers(
) → List< MarkerMatch> -
Retrieves a reference to a list of markers under the current cursor location.
inherited
-
cursorSelectionOverlayItems(
) → List< OverlayItem> -
Retrieve the list of overlay items under the cursor location.
inherited
-
cursorSelectionOverlayItemsByType(
CommonOverlayId overlayId) → List< OverlayItem> -
Retrieves overlay items of a specific type under the cursor location.
inherited
-
cursorSelectionPath(
) → Path? -
Retrieve the path under the cursor location.
inherited
-
cursorSelectionRoutes(
) → List< Route> -
Retrieve the list of routes under the cursor location.
inherited
-
cursorSelectionStreets(
) → List< Landmark> -
Retrieve the list of streets under the cursor location.
inherited
-
cursorSelectionTrafficEvents(
) → List< TrafficEvent> -
Retrieve the list of traffic events under the cursor location.
inherited
-
deactivateAllHighlights(
) → void -
Deactivates all highlight collections simultaneously.
inherited
-
deactivateHighlight(
{int? highlightId}) → void -
Deactivates highlighting for a specific highlight collection.
inherited
-
disableDrawMarkersMode(
) → List< Landmark> -
Disables marker drawing mode and retrieves the drawn landmarks.
inherited
-
dispose(
) → Future< void> - Releases native resources associated with this controller.
-
enableDrawMarkersMode(
{MarkerCollectionRenderSettings? renderSettings}) → void -
Enables interactive marker drawing mode using touch gestures.
inherited
-
getAltitude(
Coordinates coordinates) → double -
Retrieves the altitude at specified geographic coordinates.
inherited
-
getHighlight(
int highlightId) → List< Landmark> -
Retrieves the landmarks in a highlighted collection.
inherited
-
getHighlightArea(
{int highlightId = 0}) → RectangleGeographicArea? -
Retrieves the geographic bounds of a highlighted collection.
inherited
-
getIsFollowingPosition(
bool alsoFlyToPosition) → bool -
Checks if the camera is following the current position with optional animation consideration.
inherited
-
getNearestLocations(
Coordinates coords, {List< int> lmkStoreTypesIds = const <int>[], int radius = 0}) → List<Landmark> -
Retrieves nearby landmarks at specified geographic coordinates.
inherited
-
getOptimalHighlightCenterViewport(
{Rectangle< int> ? screenRect}) → Rectangle<int> -
Calculates the optimal viewport for displaying all highlighted elements.
inherited
-
getOptimalRoutesCenterViewport(
List< Route> routes, {Rectangle<int> ? screenRect}) → Rectangle<int> -
Calculates the optimal viewport for displaying multiple routes.
inherited
-
getTransferStatistics(
ViewOnlineServiceType type) → TransferStatistics -
Retrieves data transfer statistics for a specific online service.
inherited
-
getVisibleRouteInterval(
Route route, {Rectangle< int> ? screenRect}) → (int, int) -
Determines which segment of a route is visible within a screen rectangle.
inherited
-
handleEvent(
Map arguments) → void -
React to view events and call the listener functions.
inherited
-
handleTouchEvent(
int pointerIndex, int touchType, int x, int y) → GemError -
Handle a touch event delivered to the map view.
inherited
-
highlightHoveredMapLabel(
Point< int> screenPosition, {bool selectMapObject = false}) → GemError -
Highlights a map label at the specified screen coordinates.
inherited
-
isDefaultFollowingPosition(
) → bool -
Checks if follow position mode is active in its default auto-zoom configuration.
inherited
-
isFollowingPositionTouchHandlerModified(
) → bool -
Checks if follow position mode has been manually adjusted by user input.
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onCursorSelectionUpdatedLandmarks(
List< Landmark> landmarks) → void - Called when cursor-hover landmark selections are detected.
-
onCursorSelectionUpdatedMapSceneObject(
MapSceneObject mapSceneObject) → void - Called when cursor-hover map scene object selections are detected.
-
onCursorSelectionUpdatedMarkers(
List< MarkerMatch> markerMatches) → void - Called when cursor-hover marker selections are detected.
-
onCursorSelectionUpdatedOverlayItems(
List< OverlayItem> overlayItems) → void - Called when cursor-hover overlay item selections are detected.
-
onCursorSelectionUpdatedPath(
Path path) → void - Called when cursor-hover path selections are detected.
-
onCursorSelectionUpdatedRoutes(
List< Route> routes) → void - Called when cursor-hover route selections are detected.
-
onCursorSelectionUpdatedTrafficEvents(
List< TrafficEvent> trafficEvents) → void - Called when cursor-hover traffic event selections are detected.
-
onDoubleTouch(
Point< int> pos) → void - Called when a double-touch (double-tap) gesture occurs.
-
onFollowPositionState(
FollowPositionState followPositionState) → void - Called when the follow-position state changes.
-
onHoveredMapLabelHighlightedLandmark(
Landmark object) → void - Called when a hovered map label landmark is highlighted.
-
onHoveredMapLabelHighlightedOverlayItem(
OverlayItem object) → void - Called when a hovered map label overlay item is highlighted.
-
onHoveredMapLabelHighlightedTrafficEvent(
TrafficEvent object) → void - Called when a hovered map label traffic event is highlighted.
-
onLongPress(
Point< int> pos) → void - Called when a long-press gesture is detected.
-
onMapAngleUpdate(
double angle) → void - Called when the map angle (bearing) changes.
-
onMarkerRender(
dynamic data) → void - Called when marker rendering is required.
-
onMove(
Point< num> startPoint, Point<num> endPoint) → void - Called when a single-pointer move (drag) gesture occurs.
-
onPinch(
Point< int> start1, Point<int> start2, Point<int> end1, Point<int> end2, Point<int> center) → void - Called when a continuous two-pointer pinch gesture occurs.
-
onPinchSwipe(
Point< int> centerPosInPix, double zoomingSpeedInMMPerSec, double rotatingSpeedInMMPerSec) → void - Called when a two-pointer pinch-swipe gesture occurs.
-
onPointerDown(
int pointerId, Point< num> pos) → void - Called when a pointer touches down on the view.
-
onPointerMove(
int pointerId, Point< num> pos) → void - Called when a pointer moves across the view.
-
onPointerUp(
int pointerId, Point< num> pos) → void - Called when a pointer is released.
-
onRenderMapScale(
int scaleWidth, int scaleValue, String scaleUnits) → void - Called when the map scale should be rendered.
-
onSetMapStyle(
int id, String stylePath, bool viaApi) → void - Called when the map style changes.
-
onShove(
double pointersAngleDeg, Point< int> initial, Point<int> start, Point<int> end) → void - Called when a two-pointer shove gesture occurs.
-
onSwipe(
int distX, int distY, double speedMmPerSec) → void - Called when a single-pointer swipe (fling) gesture occurs.
-
onTouch(
Point< int> pos) → void - Called when a single-pointer touch down event occurs.
-
onTouchHandlerModifyFollowPosition(
FollowPositionState followPositionState) → void - Called when follow-position mode is manually adjusted by touch.
-
onTouchMove(
Point< int> startPos, Point<int> endPos) → void - Called when a touch-move gesture occurs after tap-and-hold.
-
onTouchPinch(
Point< int> start1, Point<int> start2, Point<int> end1, Point<int> end2) → void - Called when a touch-initiated pinch gesture occurs.
-
onTwoDoubleTouches(
Point< int> pos) → void - Called when a two-pointer double-touch gesture occurs.
-
onTwoTouches(
Point< int> pos) → void - Called when a simultaneous two-pointer touch gesture occurs.
-
onViewportResized(
Rectangle< int> viewportIn) → void - Called when the map viewport changes size.
-
onViewRendered(
dynamic data) → void - Called when a map frame finishes rendering.
-
registerOnCursorSelectionUpdatedLandmarks(
CursorSelectionCallback< List< ? cursorSelectionLandmarksCallback) → voidLandmark> > - Registers for cursor-hover landmark selections.
-
registerOnCursorSelectionUpdatedMapSceneObject(
CursorSelectionCallback< MapSceneObject> ? cursorSelectionMapSceneObjectCallback) → void - Registers for cursor-hover map scene object selections.
-
registerOnCursorSelectionUpdatedMarkers(
CursorSelectionCallback< List< ? cursorSelectionMarkersCallback) → voidMarkerMatch> > - Registers for cursor-hover marker selections.
-
registerOnCursorSelectionUpdatedOverlayItems(
CursorSelectionCallback< List< ? cursorSelectionOverlayItemsCallback) → voidOverlayItem> > - Registers for cursor-hover overlay item selections.
-
registerOnCursorSelectionUpdatedPath(
CursorSelectionCallback< Path> ? cursorSelectionPathCallback) → void - Registers for cursor-hover path selections.
-
registerOnCursorSelectionUpdatedRoutes(
CursorSelectionCallback< List< ? cursorSelectionRoutesCallback) → voidRoute> > - Registers for cursor-hover route selections.
-
registerOnCursorSelectionUpdatedTrafficEvents(
CursorSelectionCallback< List< ? cursorSelectionRouteTrafficCallback) → voidTrafficEvent> > - Registers for cursor-hover traffic event selections.
-
registerOnDoubleTouch(
TouchCallback? doubleTouchCallback) → void - Registers a callback for double-touch (double-tap) gestures.
-
registerOnFollowPositionState(
FollowPositionStateCallback? followPositionStateUpdatedCallback) → void - Registers for follow-position state changes.
-
registerOnHoveredMapLabelHighlightedLandmark(
HoveredMapLabelHighlightedLandmarkCallback? hoveredMapLabelHighlightedLandmarkCallback) → void - Registers for hovered map label landmark highlights.
-
registerOnHoveredMapLabelHighlightedOverlayItem(
HoveredMapLabelHighlightedOverlayItemCallback? hoveredMapLabelHighlightedOverlayItemCallback) → void - Registers for hovered map label overlay item highlights.
-
registerOnHoveredMapLabelHighlightedTrafficEvent(
HoveredMapLabelHighlightedTrafficEventCallback? hoveredMapLabelHighlightedTrafficEventCallback) → void - Registers for hovered map label traffic event highlights.
-
registerOnLongPress(
TouchCallback? touchCallback) → void - Registers a callback for long-press gestures.
-
registerOnMapAngleUpdate(
MapAngleUpdateCallback? mapAngleUpdatedCallback) → void - Registers for map angle updates.
-
registerOnMapViewMoveStateChanged(
MapViewMoveStateChangedCallback? onMapViewMoveStateChangedCallback) → void - Registers for map move start/stop events.
-
registerOnMove(
MoveCallback? moveCallback) → void - Registers a callback for single-pointer move gestures.
-
registerOnPinch(
PinchCallback? pinchCallback) → void - Registers a callback for continuous two-pointer pinch gestures.
-
registerOnPinchSwipe(
PinchSwipeCallback? pinchSwipeCallback) → void - Registers a callback for two-pointer pinch-swipe gestures.
-
registerOnRenderMapScale(
RenderMapScaleCallback? scaleCallback) → void - Registers for map scale rendering callbacks.
-
registerOnSetMapStyle(
SetMapStyleCallback? setMapStyleCallback) → void - Registers for map style change notifications.
-
registerOnShove(
ShoveCallback? shoveCallback) → void - Registers for two-pointer shove gestures.
-
registerOnSwipe(
SwipeCallback? swipeCallback) → void - Registers a callback for single-pointer swipe (fling) gestures.
-
registerOnTouch(
TouchCallback? touchCallback) → void - Registers a callback for single-pointer touch down events.
-
registerOnTouchHandlerModifyFollowPosition(
FollowPositionStateCallback? touchHandlerModifyFollowPositionCallback) → void - Registers for manual follow-position modifications triggered by touch.
-
registerOnTouchMove(
MoveCallback? touchMoveCallback) → void - Registers a callback for touch-move gestures after tap-and-hold.
-
registerOnTouchPinch(
TouchPinchCallback? touchPinchCallback) → void - Registers a callback for touch-initiated pinch gestures.
-
registerOnTwoDoubleTouches(
TouchCallback? twoDoubleTouchCallback) → void - Registers a callback for two-pointer double-touch gestures.
-
registerOnTwoTouches(
TouchCallback? twoTouchCallback) → void - Registers a callback for simultaneous two-pointer touch gestures.
-
registerOnViewportResized(
ViewportResizedCallback? viewportResizedCallback) → void - Registers for viewport resize notifications.
-
registerOnViewRendered(
MapViewRenderedCallback? onMapViewRenderedCallback) → void - Registers for map render completion notifications.
-
resetMapSelection(
) → Future< void> -
Resets the cursor to its default position at the viewport center.
inherited
-
restoreFollowingPosition(
{GemAnimation? animation}) → void -
Restores follow position mode to its default auto-zoom configuration.
inherited
-
setClippingArea(
Rectangle< double> area) → void -
Sets the view clipping rectangle using parent screen ratio coordinates.
inherited
-
setCursorScreenPosition(
Point< int> screenPosition) → Future<void> -
Updates the cursor's screen position for map selection.
inherited
-
setSlippyZoomLevel(
double zoomLevel, {int duration = 0, Point< int> ? screenPosition}) → double -
Sets the map zoom level using slippy tile-based zoom scale.
inherited
-
setZoomLevel(
int zoomLevel, {int duration = 0, Point< int> ? screenPosition}) → int -
Sets the map zoom level centered on a specified screen position.
inherited
-
skipAnimation(
{bool jumpToDestination = true}) → void -
Terminates the current map animation.
inherited
-
startFollowingPosition(
{GemAnimation? animation, int zoomLevel = -1, double? viewAngle, MapSceneObject? positionObj}) → void -
Activates follow position mode to track the current location.
inherited
-
stopFollowingPosition(
{bool restoreCameraMode = false}) → void -
Deactivates follow position mode, stopping position tracking.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
transformScreenToWgs(
Point< int> screenCoordinates) → Coordinates -
Converts screen coordinates to WGS84 geographic coordinates.
inherited
-
transformScreenToWgsRect(
{Rectangle< int> ? screenRect}) → RectangleGeographicArea -
Converts a screen rectangle to a geographic area.
inherited
-
transformWgsListToScreen(
List< Coordinates> coords) → List<Point< int> > -
Converts multiple WGS84 geographic coordinates to screen coordinates in batch.
inherited
-
transformWgsToScreen(
Coordinates coords) → Point< int> -
Converts WGS84 geographic coordinates to screen coordinates.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited