Migrate to 2.11.0

_{Estimated reading time: 7 minutes}

This guide outlines the breaking changes introduced in SDK version 2.11.0. Required updates may vary depending on your use case.

Additionally, new features and bug fixes have been introduced and are not documented here. For a comprehensive list of changes, please refer to the changelog.

XyType replaced with Point

XyType was replaced with Point throughout the MapView, GemMapController, FollowPositionPreferences classes. For a detailed list of all affected methods, refer to the changelog.

As parameter type:

For example:

mapController.transformScreenToWgs(XyType(x: 5, y: 10));

Becomes:

mapController.transformScreenToWgs(Point<int>(5, 10));

As return value:

This is the previous code:

List<XyType<int>> result = mapController.transformWgsListToScreen(coordinates);

The updated code:

List<Point<int>> result = mapController.transformWgsListToScreen(coordinates);

MarkerRenderSettings.labelingMode type was changed from int? to Set<MarkerLabelingMode>

This is the previous code:

settings.labelingMode = MarkerLabelingMode.item.id | MarkerLabelingMode.group.id

The updated code:

settings.labelingMode = {MarkerLabelingMode.itemLabelVisible, MarkerLabelingMode.groupLabelVisible}

The value passed to the constructor of MarkerRenderSettings changes in a similar way.

The startNavigation and startSimulation of NavigationService return TaskHandler? instead of TaskHandler

This is the previous code:

TaskHandler taskHandler = NavigationService.startNavigation(...);

The updated code:

TaskHandler? taskHandler = NavigationService.startNavigation(...);

info

The value null is returned when the navigation/simulation could not be started. The onError callback is also triggered with the corresponding error code.

Some methods return TaskHandler? instead of TaskHandler. Result value from the onCompleteCallback callback is no longer nullable

Affected methods and classes are:

• search, searchLandmarkDetails, searchAlongRoute, searchInArea and searchAroundPosition methods from SearchService
• calculateRoute method from RoutingService
• searchReportsAlongRoute and searchReportsAround methods from SocialOverlay

This is the previous code:

TaskHandler taskHandler = RoutingService.calculateRoute(
    landmarks,
    preferences,
    (GemError err, List<Route>? result) {
        // Compute operations with result
    },
);

The updated code:

TaskHandler? taskHandler = RoutingService.calculateRoute(
    landmarks,
    preferences,
    (GemError err, List<Route> result) {
        // Compute operations with result
    },
);

The value null is returned when the operation could not be started.

The result type also has been changed to non-nullable:

• List<Route>? result becomes List<Route> result
• List<Landmark>? result becomes List<Landmark> result
• List<OverlayItemPosition>? result becomes List<OverlayItemPosition> result

If the operation fails the onCompleteCallback callback is called with error and empty list of results. Before this update the onCompleteCallback callback was called with error and null list of results.

On success the onCompleteCallback callback is called with GemError.success and non-empty list of results as before.

Many fields from the classes are now non-nullable

A complete list of classes affected can be found in the changelog.

This is the previous code:

MarkerCollectionRenderSettings markerCollectionRenderSettings;
int? zoomLevel = markerCollectionRenderSettings.pointsGroupingZoomLevel;

The updated code:

MarkerCollectionRenderSettings markerCollectionRenderSettings;
int zoomLevel = markerCollectionRenderSettings.pointsGroupingZoomLevel;
// Perform operations with zoomLevel...

Same change applies for constructors and setters. For resetting a field to its default value pass the default value given in the constructor to the setter. The toJson and fromJson methods of these classes are also affected by this change as the JSONs generated by previous versions are no longer compatible with the current SDK version.

Register methods from GemMapController allow null parameters to be passed

For example, unregistering from a previous registerViewRenderedCallback can now be done by calling registerViewRenderedCallback(null)

Deprecated MarkerLabelingMode item and group enum values. Added itemLabelVisible and groupLabelVisible

MarkerLabelingMode.item needs to be replaced with MarkerLabelingMode.itemLabelVisible.

MarkerLabelingMode.group needs to be replaced with MarkerLabelingMode.groupLabelVisible.

arrivalTime and departureTime of the PTRouteSegment and PTRouteInstruction classes now return DateTime? instead of DateTime

If no data is available for the arrivalTime/departureTime then null will be returned.

For example, the previous code was:

DateTime arrivalTime = ptSegment.arrivalTime;

The updated code:

DateTime? departureTime = ptSegment.departureTime; 

Changed DataSource creation

The createExternalDataSource static method should be used for external data sources.

For example, the previous code was:

DataSource source = DataSource([DataType.improvedPosition]);

The updated code:

DataSource source = DataSource.createExternalDataSource([DataType.improvedPosition]);

The onNavigationInstructionUpdate callback parameter used for startNavigation and startSimulation is deprecated and will be removed

The onNavigationInstructionUpdate will is replaced by more specialized optional callbacks:

• onNavigationInstruction for getting updates about NavigationInstruction
• onDestinationReached for getting updates about reaching destination
• onError for getting updates about navigation errors

The NavigationEventType enum is now deprecated and will be removed together with the onNavigationInstructionUpdate callback.

This is the previous code:

TaskHandler taskHandler = NavigationService.startNavigation(
    routes.first,
    (eventType, instruction) {
        if (eventType == NavigationEventType.navigationInstructionUpdate) {
            // Do operation with instruction
        }
        if (eventType == NavigationEventType.destinationReached) {
            // Do operation when destination is reached
        }
        if (eventType == NavigationEventType.error) {
            // Do operation with error is triggered
        }
    },
);

The updated code:

TaskHandler? taskHandler = NavigationService.startNavigation(
    routes.first,
    null,  // <-- This positional argument will be removed in the next release
    onNavigationInstruction: (NavigationInstruction instruction, Set<NavigationInstructionUpdateEvents> events) {
        // Do operation with instruction
        // Note: details about reasons why a new instruction is trigger is now available is events 
    },
    onDestinationReached: (Landmark landmark) {
        // Do operation when destination is reached
        // Note: the destination is also provided as a landmark 
    },
    onError: (GemError error) {
        // Do operation with error is triggered
        // Note: The error is also provided
    },
);

In a future release the positional onNavigationInstructionUpdate will be removed and the null from the snippet above will not be required.

The routeTrack getter from RouteBase has been removed. Added specific class for routes built from Path

This getter was replaced by the track getter from the OTRoute class.

This is the previous code:

Path? track = route.routeTrack;

The updated code:

OTRoute? otRoute = route.toOTRoute();
if (otRoute != null){
    Path track = otRoute.track;
}

Fields from listeners are now private

For example, AlarmService provided fields such as onBoundaryCrossedCallback, onMonitoringStateChangedCallback, onTunnelEnteredCallback, etc. These fields are now hidden. Setting a callback will be done via the register methods registerOnBoundaryCrossed, registerOnMonitoringStateChanged, registerOnTunnelEntered. For unregistering a callback the same methods will be used with null parameter (on an empty callback).

Other methods such as notifyCustom, notifyComplete, notifyCompleteWithData, notifyProgress, notifyStart are now @internal and should not be used by SDK client.

All listener classes in the SDK have been affected. Refer to the changelog for a detailed list.

Fixed typos

• vizibility from MapSceneObject has been renamed to visibility
• insideCityAea parameter from AlarmService.setOverSpeedThreshold method has been renamed to insideCityArea
• getContourGeograficArea from Landmark has been renamed to getContourGeographicArea

Removed classes and methods

• The CameraConfiguration, SizeType, AutoDisposableObject, TimezoneResult have been removed as they were not used and were not functional. They are not replaced by anything.
• The fromJson method of MarkerRenderSettings and MarkerCollectionRenderSettings were removed as they are no longer used. The fromJson and toJson methods provided in the SDK classes are for internal use and should not be used by the SDK users.
• The toJson methods of the Parameter and Conditions classes are removed.
• The hasRoutesCollectionInit, hasPathCollectionInit, hasFollowPositionPrefsInit fields from MapViewPreferences class were removed as they are no longer used. The methods/getters from MapViewPreferences can be used without any checks.

Changes to the RouteInstruction hierarchy

Previously, PTRouteInstruction and EVRouteInstruction were subclasses of RouteInstruction.

With the new change, RouteInstruction, PTRouteInstruction, and EVRouteInstruction now inherit from a new base class, RouteInstructionBase.

As a result, the methods toEVRouteInstruction and toPTRouteInstruction are now available only on the RouteInstruction type. SDK users who relied on the polymorphic behavior of the RouteInstruction class in their code may need to adjust their implementation to accommodate these changes.

Changes to the RouteSegment hierarchy

Previously, PTRouteSegment and EVRouteSegment were subclasses of RouteSegment.

With the new change, RouteSegment, PTRouteSegment, and EVRouteSegment now inherit from a new base class, RouteInstructionBase.

As a result, the methods toEVRouteSegment and toPTRouteSegment are now available only on the RouteSegment type. SDK users who relied on the polymorphic behavior of the RouteSegment class in their code may need to adjust their implementation to accommodate these changes.