CartoType UWP API 8.10-3-g0075538f6
for development in C#, VB.NET and C++
Public Member Functions | Properties | List of all members
CartoType::Framework Class Reference

The Framework class provides a high-level API for CartoType, through which map data can be loaded, maps can be created and viewed, and routing and navigation can be performed. More...

#include <CartoTypeWrapper.h>

Public Member Functions

 Framework (String^ aMapFileName, String^ aStyleSheetFileName, String^ aFontFileName, int aViewWidth, int aViewHeight)
 Creates a CartoType framework with a map, style sheet, font, and view size in pixels.
 
 Framework (String^ aMapFileName, String^ aStyleSheetFileName, String^ aFontFileName, int aViewWidth, int aViewHeight, String^ aEncryptionKey)
 Creates a CartoType framework with an encrypted map, style sheet, font, and view size in pixels.
 
 Framework (FrameworkParam^ aParam)
 Creates a CartoType framework from parameters contained in a FrameworkParam object.
 
Result License (String^ aKey)
 Licenses the CartoType framework by supplying a key.
 
Result SetProviderParam (String^ aKey, String^ aValue)
 Sets a parameter to be used by a data provider. For example, to set the 'permanent' parameter used by the Mapbox geocoding API, call SetProviderParam("mapbox/geocoding/permanent","true"). If aValue is empty, the entry for aKey is deleted.
 
void SetCopyrightNotice ()
 Sets the copyright notice displayed at the bottom-right corner of the map to that of the main map database.
 
void SetCopyrightNotice (String^ aCopyright)
 Sets the copyright notice displayed at the bottom-right corner of the map.
 
void SetLegend (Legend^ aLegend, double aWidth, String^ aUnit, NoticePosition aPosition)
 Sets the legend: map key or scale or both.
 
void SetLegendExtended (Legend^ aLegend, double aWidth, String^ aUnit, ExtendedNoticePosition^ aPosition)
 Sets the legend: map key or scale or both.
 
void SetScaleBar (double aWidth, String^ aUnit, NoticePosition aPosition)
 Creates a scale bar with a specified width and position in the display.
 
void SetScaleBarExtended (double aWidth, String^ aUnit, ExtendedNoticePosition^ aPosition)
 Creates a scale bar with a specified width and position in the display.
 
Result SetTurnInstructions (bool aAbbreviate, double aWidth, String^ aWidthUnit, NoticePosition aPosition, double aTextSize, String^ aTextSizeUnit)
 Creates turn instructions with a specified width and position in the display.
 
Result SetTurnInstructionsExtended (bool aAbbreviate, double aWidth, String^ aWidthUnit, ExtendedNoticePosition^ aPosition, double aTextSize, String^ aTextSizeUnit)
 Creates turn instructions with a specified width and position in the display.
 
void SetTurnInstructionText (String^ aText)
 Sets the instruction to be displayed for the current turn, overriding automatically generated instructions. More...
 
void DrawNoticesAutomatically (bool aEnable)
 Controls whether notices (the scale bar, legend and copyright notice) are drawn automatically.
 
Result Configure (String^ aConfigFileName)
 Configures the CartoType framework by reading an XML configuration file.
 
Result LoadMap (String^ aMapFileName)
 Loads a map to be overlaid on the current map.
 
Result LoadMap (String^ aMapFileName, String^ aEncryptionKey)
 Loads an encrypted map to be overlaid on the current map.
 
Result CreateWritableMap (WritableMapType aType)
 Creates a writable (editable) map of the specified type and loads it.
 
Result CreateWritableMap (WritableMapType aType, String^ aFileName)
 Creates a writable (editable) map of the specified type, supplying a filename, and loads it.
 
Result SaveMap (int aHandle, String^ aFileName, FileType aFileType)
 Saves a map identified by its handle by writing it the specified format. Only writable map databases may be saved in this way. Only the CTMS (CartoType Map Serialized) and Keyhole Markup Language (KML) formats are supported.
 
Result ReadMap (int aHandle, String^ aFileName, FileType aFileType)
 Reads map data from aFileName in the format given by aFileType and merge it into the map identified by aHandle, which must refer to a writable map database. Only the CTMS (CartoType Map Serialized) and Keyhole Markup Language (KML) formats are supported.
 
Result WriteMapImage (String^ aFileName, FileType aFileType, bool aCompress)
 Writes a map image to a file of the specified type. Only the PNG file type is supported. If aCompress is true, compress the file if possible. This is done by means of palettization for PNG files.
 
bool MapIsEmpty (int aHandle)
 Return true if a map, identified by its handle, is known to be empty or does not exist.
 
int MapHandle (int aIndex)
 Returns the handle of one of the currently loaded maps. Returns 0 if aIndex is out of range.
 
bool MapIsWritable (int aIndex)
 Returns true if the indexed map is writable.Returns false if aIndex is out of range.
 
MapMetaDataMapMetaData (int aIndex)
 Returns the metadata for a map, identified by its index, if available. Returns null if no metadata is available. Metadata is currently available only for CTM1 maps.
 
Result UnloadMapByHandle (int aHandle)
 Unloads a map, selecting it by handle. It is illegal to unload the main map database or the in-memory database.
 
void EnableMapByHandle (int aHandle, bool aEnable)
 Enables or disables a map, selecting it by handle.
 
void EnableAllMaps ()
 Enables all currently loaded maps.
 
Result LoadFont (String^ aFontFileName)
 Loads a font in addition to those already loaded.
 
Result SetStyleSheet (String^ aStyleSheetFileName, int aIndex)
 Sets a style sheet by loading it from a file. The index aIndex determines which style sheet to replace: 0 means the main style sheet, and numbers from 1 up refer to extra style sheets.
 
Result SetStyleSheetData (String^ aData, int aIndex)
 Sets a style sheet by loading it from data in memory. More...
 
Result ReloadStyleSheet (int aIndex)
 Reloads a sheet from the file it was originally loaded from. More...
 
void AppendStyleSheet (String^ aStyleSheetFileName)
 Loads an extra style sheet from a file. Extra style sheets are compiled after the main style sheet.
 
void AppendStyleSheetData (String^ aData)
 Loads an extra style sheet from data in memory. Extra style sheets are compiled after the main style sheet.
 
Result DeleteStyleSheet (int aIndex)
 Deletes the style sheet with the specified index. More...
 
void EnableLayer (String^ aLayerName, bool aEnable)
 Enables or disables a named map layer.
 
bool LayerIsEnabled (String^ aLayerName)
 Returns the enabled status of a named layer. When a layer is disabled it is not drawn but is still searchable.
 
Result Resize (int aViewWidth, int aViewHeight)
 Sets the map to a new size in pixels.
 
double DistanceInMeters (double aX1, double aY1, double aX2, double aY2, CoordType aCoordType)
 Returns the great-circle distance in meters, assuming a spherical earth, between two points.
 
double ScaleDenominatorFromZoomLevel (double aZoomLevel, int aImageSizeInPixels)
 Calculates the scale denominator at the equator for a certain Open Street Map zoom level (0 maps the length of the equator to aImageSizeInPixels pixels, 1 = half the length of the equator, etc.).
 
double ZoomLevelFromScaleDenominator (double aScaleDenominator, int aImageSizeInPixels)
 Calculates the Open Street Map zoom level (0 maps the length of the equator to aImageSizeInPixels pixels, 1 = half the length of the equator, etc.) for a certain scale denominator.
 
void SetPerspective (bool aSet)
 Turns perspective mode on or off.
 
Result Zoom (double aZoomFactor)
 Zooms the map by the specified factor: positive to zoom in, negative to zoom out.
 
Result ZoomAt (double aZoomFactor, double aX, double aY, CoordType aCoordType)
 Zooms in by a specified zoom factor, or zooms out if the zoom factor is less than 1, centering the zoom at the specified position, so that it remains at the same place on the display. More...
 
Result Rotate (double aAngle)
 Rotates the map by an angle given in degrees.
 
Result RotateAt (double aAngle, double aX, double aY, CoordType aCoordType)
 Rotates the map about a specified point by an angle given in degrees.
 
Result SetRotationAt (double aAngle, double aX, double aY, CoordType aCoordType)
 Sets the map's orientation to a rotation about a specified point by an absolute angle given in degrees.
 
Result RotateAndZoom (double aAngle, double aZoomFactor, double aX, double aY, CoordType aCoordType)
 Simultaneously rotates and zooms at a certain point given in aCoordType. The rotation is in degrees.
 
void Pan (int aDx, int aDy)
 Moves the map by aDx pixels horizontally and aDy pixels vertically.
 
Result Pan (double aFromX, double aFromY, CoordType aFromCoordType, double aToX, double aToY, CoordType aToCoordType)
 Pans (slides) the map so that the position aFrom moves to aTo.
 
Result SetViewCenter (double aX, double aY, CoordType aCoordType)
 Sets the center of the view to a point given in display pixels, map coordinates or degrees longitude and latitude.
 
Result SetView (double aX1, double aY1, double aX2, double aY2, CoordType aCoordType, int aMarginInPixels, int aMinScaleDenominator)
 Sets the view to show a certain rectangle, with a margin in pixels, and at a minimum scale.
 
void SetView (MapObject^ aMapObject, int aMarginInPixels, int aMinScaleDenominator)
 Sets the view to show a single map object, with a margin in pixels, and at a minimum scale.
 
Result SetViewToMapObjects (MapObjectList^ aObjectList, int aMarginInPixels, int aMinScaleDenominator)
 Sets the view to show a group of map objects, with a margin in pixels, and at a minimum scale.
 
Result SetViewToGeometry (Geometry^ aGeometry, int aMarginInPixels, int aMinScaleDenominator)
 Sets the view to show a certain geometry, with a margin in pixels, and at a minimum scale.
 
Result SetViewToRoute (int aRouteIndex, int aMarginInPixels, int aMinScaleDenominator)
 Sets the view to show a route selected by its index (0 for the main route), with a margin in pixels, and at a minimum scale.
 
Result SetViewToWholeMap ()
 Shows the whole map, zooming out as far as necessary.
 
Result SetViewLimits (double aMinScaleDenominator, double aMaxScaleDenominator, Geometry^ aPanArea)
 Sets the limits to zooming and panning. More...
 
Result GetView (Rect^ aView, CoordType aCoordType)
 Gets the view rectangle in display pixels, map coordinates or degrees longitude and latitude.
 
Result GetMapExtent (Rect^ aExtent, CoordType aCoordType)
 Gets the extent of the map in display pixels, map coordinates or degrees longitude and latitude.
 
Result InsertMapObject (int aMapHandle, String^ aLayerName, Geometry^ aGeometry, String^ aStringAttributes, FeatureInfo^ aFeatureInfo, MapObjectId^ aId, bool aReplace)
 Inserts a map object into one of the writable maps. The type of the map object (point, line or polygon) is deduced from the geometry object. If aMapHandle is zero the in-memory map used for routing is used. More...
 
Result InsertPointMapObject (int aMapHandle, String^ aLayerName, double aX, double aY, CoordType aCoordType, String^ aStringAttributes, FeatureInfo^ aFeatureInfo, MapObjectId^ aId, bool aReplace)
 Inserts a point object into one of the writable maps, identifying it by its handle. If aMapHandle is zero the in-memory map used for routing is used. More...
 
Result InsertCircleMapObject (int aMapHandle, String^ aLayerName, double aCenterX, double aCenterY, CoordType aCenterCoordType, double aRadius, CoordType aRadiusCoordType, String^ aStringAttributes, FeatureInfo^ aFeatureInfo, MapObjectId^ aId, bool aReplace)
 Inserts a circle map object into one of the maps, identifying the map by its handle. If aMapHandle is zero the in-memory map used for routing is used. More...
 
Result InsertEllipseMapObject (int aMapHandle, String^ aLayerName, double aCenterX, double aCenterY, CoordType aCenterCoordType, double aRadiusX, double aRadiusY, CoordType aRadiusCoordType, double aRotationDegrees, String^ aStringAttributes, FeatureInfo^ aFeatureInfo, MapObjectId^ aId, bool aReplace)
 Inserts an ellipse map object into one of the maps, identifying the map by its handle. If aMapHandle is zero the in-memory map used for routing is used. More...
 
Result InsertEnvelopeMapObject (int aMapHandle, String^ aLayerName, Geometry^ aGeometry, double aRadius, CoordType aRadiusCoordType, String^ aStringAttributes, FeatureInfo^ aFeatureInfo, MapObjectId^ aId, bool aReplace)
 Inserts a map object that is an envelope around some geometry, at a radius of aRadius; it can also be regarded as a stroke drawn along the path with a stroke width of twice aRadius. More...
 
Result InsertPushPin (double aX, double aY, CoordType aCoordType, String^ aStringAttributes, String^ aColor, int aIconCharacter, MapObjectId^ aId)
 Inserts a pushpin: a point object belonging to the 'pushpin' layer. The pushpin is inserted into the built-in modifiable map. More...
 
Result InsertCopyOfMapObject (int aMapHandle, String^ aLayerName, MapObject^ aObject, double aEnvelopeRadius, CoordType aRadiusCoordType, MapObjectId^ aId, bool aReplace)
 Inserts an object by copying an existing object. More...
 
Result DeleteMapObjects (int aMapHandle, int64_t aStartId, int64_t aEndId, String^ aCondition)
 Deletes map objects with IDs in the range aStartId...aEndId inclusive. If aCondition is non-null, delete objects satisfying aCondition only.
 
MapObjectLoadMapObject (int aMapHandle, int64_t aId)
 Loads a map object, identifying it by its map handle and ID. Returns null if the object does not exist.
 
Result ReadGpx (int aMapHandle, String^ aFileName)
 Reads route and track objects from a GPX file and inserts them into the map identified by aMapHandle. This function fails if the map is not writable. More...
 
GeometryRange (RouteProfile^ aProfile, double aX, double aY, CoordType aCoordType, double aTimeOrDistance, bool aIsTime)
 Returns the range: a polygon containing the area reachable within a certain time in seconds or distance in meters. More...
 
TimeAndDistanceMatrixTimeAndDistanceMatrix (IVector< PointValue >^ aFrom, IVector< PointValue >^ aTo, CoordType aCoordType)
 Returns a vector of route times in seconds and distances in metres from aFrom to all points in aTo. More...
 
bool MutuallyAccessible (IVector< PointValue >^ aPointArray, CoordType aCoordType, IVector< int >^ aGroupArray)
 Determines the mutual accessibility of a set of points for routing purposes, using the current routing profile. This function is implemented only for the turn-expanded router. More...
 
double Area (Geometry^ aGeometry)
 Returns the area of a geometry object on the surface of the earth in square meters using the WGS84 ellipsoid. More...
 
double Length (Geometry^ aGeometry)
 Returns the length of a geometry object on the surface of the earth in meters using the WGS84 ellipsoid. More...
 
double ContourArea (Geometry^ aGeometry, int aContourIndex)
 Returns the area of a geometry object on the surface of the earth in square meters using the WGS84 ellipsoid. More...
 
double ContourLength (Geometry^ aGeometry, int aContourIndex)
 Returns the length of a geometry object on the surface of the earth in meters using the WGS84 ellipsoid. More...
 
Result ConvertCoords (Geometry^ aGeometry, CoordType aToCoordType)
 Converts the coordinates of a geometry object to another coordinate type.
 
Result ConvertPoint (Point^ aPoint, CoordType aFromCoordType, CoordType aToCoordType)
 Converts a point between display pixels, map coordinates and degrees longitude and latitude.
 
double PixelsToMeters (double aPixels)
 Converts a distance in pixels to map meters (projected meters).
 
double MetersToPixels (double aMeters)
 Converts a distance in map meters (projected meters) to pixels.
 
Result EditSetWritableMap (int aMapHandle)
 Sets the map used to store editable objects. Does not affect objects already created. If this function is not called, editable objects are stored in the map used for route objects.
 
Result EditNewLineObject (double aX, double aY)
 Creates a new editable line object starting at the specified point in display coordinates.
 
Result EditNewPolygonObject (double aX, double aY)
 Creates a new editable polygon object starting at the specified point in display coordinates.
 
Result EditMoveCurrentPoint (double aX, double aY)
 Moves the editable object's current point if any to the specified point in display coordinates.
 
Result EditAddCurrentPoint ()
 Adds a new point to the editable object by copying the current point.
 
Result EditDeleteCurrentPoint ()
 Deletes the editable object's current point unless that would result in a line object of fewer than 2 points, or a polygon object of fewer than 3.
 
Result EditDeleteCurrentObject ()
 Deletes the current editable object.
 
Result EditSelectNearestPoint (double aX, double aY, double aRadiusInMillimeters)
 Selects an editable object by selecting the nearest point of any editable object within a given radius of (aX,aY), which is a point in display coordinates. More...
 
Result EditInsertCurrentObject (String^ aLayer, MapObjectId^ aId, bool aReplace)
 Inserts the currently edited object into a chosen layer. More...
 
Result EditSetCurrentObjectStringAttribute (String^ aKey, String^ aValue)
 Sets a string attribute in the currently edited object. If aKey is empty, sets the label. If aValue is empty, deletes the attribute.
 
Result EditSetCurrentObjectFeatureInfo (FeatureInfo^ aFeatureInfo)
 Sets the feature info of the currently edited object.
 
double EditGetCurrentObjectArea ()
 Returns the area of the currently edited object. For line objects returns 0. For polygon objects returns the area in square meters.
 
double EditGetCurrentObjectLength ()
 Returns the length of the currently edited object. For line objects the length in meters. For polygon objects returns the perimeter in meters.
 
void DrawMemoryDataBase (bool aEnable)
 Enables or disables the drawing of the in-memory database when the rest of the map is drawn. More...
 
bool ClipBackgroundToMapBounds (bool aEnable)
 Enables or disables clipping the map background to the map bounds. More...
 
int SetTileOverSizeZoomLevels (int aLevels)
 Sets the number of zoom levels by which to zoom out when creating a tile bitmap returned by TileBitmap(). More...
 
Result LoadIcon (String^ aFileName, String^ aId, int aHotSpotX, int aHotSpotY, int aLabelX, int aLabelY)
 Loads an icon from a file. It will be used whenever the ID aId is referenced in the style sheet, overriding any icon specified in the style sheet. More...
 
void UnloadIcon (String^ aId)
 Unloads an icon previously loaded using LoadIcon.
 
Result FindInDisplay (MapObjectList^ aObjectList, int aMaxObjectCount, double aX, double aY, double aRadius)
 Finds all objects within aRadius of the point aX,aY on the display. More...
 
Result FindAddress (MapObjectList^ aObjectList, int aMaxObjectCount, Address^ aAddress, bool aFuzzy)
 Finds objects matching the specified address, which must have at least one field that is not empty.
 
Result FindInLayer (MapObjectList^ aObjectList, int aMaxObjectCount, String^ aLayer, double aMinX, double aMinY, double aMaxX, double aMaxY, CoordType aCoordType)
 Finds all objects in a named layer or list of layers (space or comma separated), within specified bounds.
 
Result FindText (MapObjectList^ aObjectList, int aMaxObjectCount, String^ aText, StringMatchMethod aMatchMethod, String^ aLayers, String^ aAttrib)
 Finds objects with attributes matching aText. More...
 
Result Find (MapObjectList^ aObjectList, FindParam^ aFindParam)
 A general search function, allowing any combination of clip rectangle, choice of layers, choice of attributes, text and string match method.
 
Result FindGroups (MapObjectGroupList^ aObjectGroupList, FindParam^ aFindParam)
 A search function to make interactive searching easier. It returns map objects grouped by names which can be used to identify the groups in a list box. For example, a search for pubs using the word 'Red' as the search term might return one group with the name 'Red Lion' and another group with the name 'Red Cow'.
 
Result FindNearby (MapObjectList^ aObjectList, FindNearbyParam^ aFindNearbyParam)
 Finds nearby objects, allowing a choice of point of interest type, name and location.
 
Result FindPolygonsContainingPath (MapObjectList^ aObjectList, Geometry^ aPath, FindParam^ aFindParam)
 Finds all polygon objects containing a certain path. More...
 
Result FindPointsInPath (MapObjectList^ aObjectList, Geometry^ aPath, FindParam^ aFindParam)
 Finds all point objects contained in a certain path. More...
 
int Height (double aX, double aY, CoordType aCoordType)
 Returns the height in metres at a single point, or -32768 if it is unavailable. More...
 
void SetStyleSheetVariableToString (String^ aVariableName, String^ aValue)
 Sets a style sheet variable to a string value.
 
void SetStyleSheetVariableToInt (String^ aVariableName, int aValue)
 Sets a style sheet variable to an integer value.
 
String ^ GeoCodeSummary (MapObject^ aMapObject)
 Returns a string summarizing a geocode for a map object. More...
 
Result GetAddress (Address^ aAddress, MapObject^ aMapObject)
 Creates an address for a map object. More...
 
Result GetAddressFast (Address^ aAddress, MapObject^ aMapObject)
 Creates an address for a map object, using attributes of the object only. Returns ErrorNotFound if the relevant address parts were not found.
 
String ^ GeoCodeSummary (double aX, double aY, CoordType aCoordType)
 Returns a string summarizing a geocode for a geographical location. More...
 
Result GetAddress (Address^ aAddress, double aX, double aY, CoordType aCoordType)
 Creates an address for a point in the map. More...
 
Result StartNavigation (RouteCoordSet^ aCoordSet)
 Starts navigating through a series of at least two points. Call Navigate as needed to supply the vehicle position.
 
Result StartNavigationDeferred (RouteCoordSet^ aCoordSet)
 Starts navigating through a series of at least two points. Call Navigate as needed to supply the vehicle position. Creates the initial route asynchronously.
 
Result StartNavigation (IVector< double >^ aX, IVector< double >^ aY, CoordType aCoordType)
 A version of StartNavigation taking separate arrays of X and Y coords.
 
Result StartNavigation (double aStartX, double aStartY, CoordType aStartCoordType, double aEndX, double aEndY, CoordType aEndCoordType)
 Starts navigating between the specified points. Call Navigate as needed to supply the vehicle position.
 
RouteCreateRoute (RouteProfile^ aProfile, RouteCoordSet^ aCoordSet)
 Creates a route without starting navigation, supplying a route profile and waypoints.
 
RouteCreateRoute (RouteProfile^ aProfile, IVector< double >^ aX, IVector< double >^ aY, CoordType aCoordType)
 A version of CreateRoute taking separate arrays of X and Y coords.
 
Result ReverseRoutes ()
 Reverses the order of the current route points, recreates the route or routes, and displays them on the map. The two directions of the same route may not follow the same path because of one-way streets and turn restrictions.
 
Result DeleteRoutes ()
 Deletes all routes.
 
RouteCreateBestRoute (RouteProfile^ aProfile, RouteCoordSet^ aCoordSet, bool aStartFixed, bool aEndFixed, int aIterations)
 Creates an optimized route to visit a series of waypoints in any order. More...
 
RouteCreateBestRoute (RouteProfile^ aProfile, IVector< double >^ aX, IVector< double >^ aY, CoordType aCoordType, bool aStartFixed, bool aEndFixed, int aIterations)
 A version of CreateBestRoute taking separate arrays of X and Y coords.
 
RouteCreateRouteFromXml (RouteProfile^ aProfile, String^ aFilenameOrData)
 Creates a route by reading it from XML data in GPX or CartoType route format. More...
 
Result UseRoute (Route^ aRoute, bool aReplace)
 Use an existing route and display it. More...
 
String ^ RouteInstructions (Route^ aRoute)
 Returns instructions for a route in the language of the current locale, or in English if that language is not available.
 
void EndNavigation ()
 Stops navigating. Current routes remain in existence. Navigation can be resumed using startNavigation or enableNavigation.
 
Result LoadNavigationData ()
 Loads navigation data for the current map. More...
 
Result SetMainProfile (RouteProfile^ aProfile)
 Sets the main routing profile. More...
 
RouteProfileProfile (int aIndex)
 Returns one of the active route profiles, or null if the index is out of range. The index 0 always works, and returns the main profile.
 
RouteProfileBuiltInProfile (int aIndex)
 Returns a built-in routing profile selected by its index, or null if the index is out of range. More...
 
Result SetBuiltInProfile (int aIndex)
 Selects a built-in routing profile by its index. More...
 
Result AddProfile (RouteProfile^ aProfile)
 Adds a new routing profile. More...
 
Result ChooseRoute (int aRouteIndex)
 Chooses one among a set of alternative routes. More...
 
Result DisplayRoute (bool aEnabled)
 If enabled, displays the current route and a maximum of 2 alternative routes. If not, removes the current route from the display.
 
RouteRoute (int aRouteIndex)
 Returns one of the current routes. Returns null if not navigating.
 
Result ReadRouteFromXml (String^ aFileNameOrData, bool aReplace)
 Reads a route from XML (a GPX file or a CartoType route file) and displays it. More...
 
Result WriteRouteAsXml (CartoType::Route^ aRoute, String^ aFileName, FileType aFileType)
 Writes a route as XML in the format selected by aFileType: CartoTypeRoute or Gpx.
 
String ^ WriteRouteAsXmlString (CartoType::Route^ aRoute, FileType aFileType)
 Writes a route as XML string in the format selected by aFileType: CartoTypeRoute or Gpx.
 
Result Navigate (int aValidity, double aTime, double aLong, double aLat, double aSpeed, double aBearing, double aHeight)
 Updates the vehicle position and, if navigating, updates the navigation state. More...
 
int SetNearbyObjectWarning (int aId, String^ aLayer, String^ aCondition, double aMaxDistance, int aMaxObjectCount)
 Adds or replaces a nearby object warning. More...
 
int SetVehicleTypeWarning (double aMaxDistance, int aMaxObjectCount)
 Adds a vehicle type warning and returns its ID. Road sections illegal for the current vehicle weight, dimensions or cargo type are found. More...
 
bool DeleteNearbyObjectWarning (int aId)
 Deletes the nearby object warning or vehicle type warning with an ID of aId and returns true if any such object existed.
 
bool ClearNearbyObjectWarnings ()
 Clears all nearby object warnings, and the objects themselves, and returns true if any objects were deleted.
 
MapObjectListCopyNearbyObjects ()
 Returns copies of all the objects for which nearby object warnings exist.
 
Result FindNearestRoad (NearestRoadInfo^ aInfo, double aX, double aY, CoordType aCoordType, double aHeadingInDegrees, bool aDisplayPosition)
 Finds the nearest road to the point (aX,aY), returns information about it in aInfo, and optionally (if aDisplayPosition is true) sets the current location to that position. Uses the current location match parameters. More...
 
Result DisplayPositionOnNearestRoad (double aLong, double aLat, double aHeadingInDegrees, NearestRoadInfo^ aInfo)
 Moves the route position object and the route vector object to the nearest point on a road. More...
 
void SetVehiclePosOffset (double aXOffset, double aYOffset)
 Sets the vehicle position when navigating as an offset from the center of the display, in units of the width and height of the display. For example, to show the vehicle in the middle but three quarters of the way down the display, use (0,0.25).
 
Result GetNavigationPosition (Point^ aPos, CoordType aCoordType)
 Returns the current position used by the navigation system. This may be an extrapolated position.
 
String ^ DistanceToString (double aDistanceInMeters, bool aAbbreviate)
 Returns a distance as a string containing locale-dependent words for kilometres, metres, miles and yards.
 
String ^ TimeToString (double aTimeInSeconds)
 Returns a time duration as a string containing locale-dependent words for hours, minutes and seconds.
 
String ^ SetCase (String^ aString, LetterCase aCase)
 Sets the letter case of a string. More...
 
Result AddTrafficInfo (MapObjectId^ aId, TrafficInfo^ aTrafficInfo, LocationRef^ aLocationRef)
 Adds traffic information, such as a speed restriction, prohibition on the use of a route, reduction in the number of lanes, notification of road works, etc. At present only speed restrictions are supported. More...
 
Result AddPolygonSpeedLimit (MapObjectId^ aId, Geometry^ aPolygon, double aSpeed, int aVehicleTypes)
 Adds a speed limit in kph, to be used when calculating routes, to all roads in a certain polygon. More...
 
Result AddLineSpeedLimit (MapObjectId^ aId, Geometry^ aLine, double aSpeed, int aVehicleTypes)
 Adds a speed limit in kph, to be used when calculating routes, to a route defined by a series of points. More...
 
Result AddClosedLineSpeedLimit (MapObjectId^ aId, Geometry^ aLine, double aSpeed, int aVehicleTypes)
 Adds a speed limit in kph, to be used when calculating routes, to a polygon which is the interior of a closed line along roads, defined by a series of points. More...
 
Result AddForbiddenArea (MapObjectId^ aId, Geometry^ aPolygon)
 Marks a certain polygon as forbidden for routing. More...
 
Result DeleteTrafficInfo (int64_t aId)
 Deletes traffic information: a speed limit, forbidden area, or other information, referring to it by the ID returned when the restriction was added by AddTrafficInfo, AddLineSpeedLimit(), AddForbiddenArea(), etc. More...
 
void ClearTrafficInfo ()
 Deletes all speed restrictions, forbidden areas and other traffic information.
 
void StartTracking ()
 Starts tracking (storing and displaying track points) and starts a new track segment. If tracking is turned on, a track point is added every time a new position fix is supplied using Navigate, if the position is far enough from the previous track point.
 
void EndTracking ()
 Stops tracking (storing and displaying track points). Does not delete the current track.
 
void DeleteTrack ()
 Deletes the current track. Does not affect whether tracking is on or off.
 
bool Tracking ()
 Returns true if tracking (storing and displaying track points) is on.
 
Result WriteTrackAsXml (String^ aFileName)
 Writes the current track to a file as XML in GPX format.
 

Properties

String^ Licensee [get]
 The name of the licensee. It is "no licensee: for evaluation only" if there is no licensee.
 
String^ ExpiryDate [get]
 Returns the expiry date of the license in the form YYYY-MM-DD.
 
String^ AppBuildDate [get]
 Returns the date on which the application was built in the form YYYY-MM-DD.
 
String^ Copyright [get]
 Returns the copyright string stored in the main map database.
 
bool LegendEnabled [get, set]
 Enables or disables the drawing of a legend that has been supplied using SetLegend.
 
bool ScaleBarEnabled [get, set]
 Enables or disables the drawing of a scale bar that has been supplied using SetScale.
 
bool TurnInstructionsEnabled [get, set]
 Enables or disables the drawing of a turn instruction notice that has been supplied using SetTurnInstructions.
 
String^ TurnInstructionText [get]
 Returns the instruction to be displayed for the current turn. This function returns an empty string if turn instructions have not been created using SetTurnInstructions.
 
bool HasNotices [get]
 Returns true if any notices such as a scale bar, legend or copyright notice exist.
 
int MapCount [get]
 Returns the number of maps currently loaded, including the main map and the in-memory map.
 
int LastMapHandle [get]
 The handle of the map most recently loaded.
 
int MainMapHandle [get]
 The handle of the main map.
 
int MemoryMapHandle [get]
 The handle of the in-memory map used for routing.
 
IVector< String^>^ LayerNames [get]
 Returns the names of all the layers in the map data.
 
double ResolutionDpi [get, set]
 The display resolution used by CartoType in dots per inch. It has to be set correctly for map scaling and lettering to work.
 
double ScaleDenominator [get, set]
 The current scale denominator. Use the denominator 50000 for a scale of 1:50,000.
 
double ScaleDenominatorInView [get, set]
 The scale denominator for the current view, adjusting for any projection distortion: for example, use the denominator 50000 for a scale of 1:50,000.
 
bool Perspective [get, set]
 Perspective mode: on or off.
 
PerspectiveParamPerspectiveParam [get, set]
 The current perspective parameters. Setting them turns perspective mode on.
 
bool Draw3DBuildings [get, set]
 Whether buildings are drawn in 3D where data is available.
 
bool AnimateTransitions [get, set]
 Whether transitions are smoothly animated in graphics-accelerated drawing.
 
double LabelFPS [get, set]
 The number of frames per second used when drawing labels. Clamped to the range 1...30.
 
bool FixedLabels [get, set]
 True if labels are drawn, as far as possible, in fixed positions, and not moved when the map is panned. More...
 
double LabelUpAngle [get, set]
 The up direction for labels as an angle in degrees measured clockwise from straight up.
 
double Rotation [get, set]
 The angle of the map in degrees, measured clockwise from north-up.
 
String^ ProjectionAsProj4Param [get]
 Returns the current map projection as a proj.4 parameter string if possible. If not returns the empty string.
 
ViewStateViewState [get, set]
 The current view state, which specifies the display size, view rectangle, rotation and whether perspective is used.
 
String^ DataSetName [get]
 Returns the name of the data in the main map database.
 
bool NightMode [get, set]
 In night mode the map is shaded dark blue and roads are made brighter than other features.
 
Color NightModeColor [get, set]
 The night mode color, which should be a dark color (although this is not enforced). More...
 
BlendStyleSetBlendStyleSet [get, set]
 The blend style. To remove the current blend style, set it to null or empty. More...
 
RouterType PreferredRouterType [get, set]
 The preferred type of router to be used for calculating routes. More...
 
RouterType ActualRouterType [get]
 The actual router type. More...
 
bool NavigationEnabled [get, set]
 Whether navigation is enabled. When navigation is disabled, the follow modes work but no navigation is performed even if there is a route.
 
int BuiltInProfileCount [get]
 Returns the number of built-in routing profiles owned by the router. More...
 
int RouteCount [get]
 The number of routes; zero if not navigating.
 
TurnFirstTurn [get]
 The first turn during navigation. More...
 
TurnSecondTurn [get]
 The second turn during navigation. More...
 
TurnContinuationTurn [get]
 The continuation turn during navigation. More...
 
NavigationState NavigationState [get]
 The current navigation state.
 
NavigatorParamNavigatorParam [get, set]
 Parameters affecting the working of the navigation system.
 
LocationMatchParamLocationMatchParam [get, set]
 The current location match parameters. More...
 
int NavigationMinimumFixDistance [get, set]
 Sets the minimum distance between location fixes in metres that is taken as an actual move.
 
int NavigationTimeOffRouteTolerance [get, set]
 Sets the maximum distance from the route in metres before the vehicle is deemed off-route.
 
int NavigationDistanceOffRouteTolerance [get, set]
 Sets the maximum time off route in seconds before a new route is calculated.
 
double DistanceToDestination [get]
 Returns the distance to the destination in metres. Return zero if there is no route.
 
double EstimatedTimeToDestination [get]
 Returns the estimated time to the destination in seconds. Return zero if there is no route.
 
CartoType::FollowMode FollowMode [get, set]
 The follow mode, which controls the way the map tracks the user location and heading.
 
String^ Locale [get, set]
 The locale used when getting the names of map objects when routing, geocoding, etc. The returned value is either a null-terminated string, usually a two-letter language identifier like 'en' for English or 'fr' for French, or an empty string meaning 'no locale'.
 
bool MetricUnits [get, set]
 Whether metric or non-metric units are used for distances.
 
bool TrafficInfoEnabled [get, set]
 Whether traffic information is used when routing.
 
bool DisplayTrack [get, set]
 Whether the track is displayed.
 
GeometryTrack [get]
 Returns the current track as a geometry object with coordinates in degrees. Each segment of the track is a contour in the geometry object.
 
double TrackLengthInMeters [get]
 The length of the current track in meters.
 
String^ TrackAsXmlString [get]
 Writes the current track to a string as XML in GPX format.
 

Detailed Description

The Framework class provides a high-level API for CartoType, through which map data can be loaded, maps can be created and viewed, and routing and navigation can be performed.

Member Function Documentation

◆ AddClosedLineSpeedLimit()

Result CartoType::Framework::AddClosedLineSpeedLimit ( MapObjectId aId,
Geometry aLine,
double  aSpeed,
int  aVehicleTypes 
)

Adds a speed limit in kph, to be used when calculating routes, to a polygon which is the interior of a closed line along roads, defined by a series of points.

aId is used to return an identifier for the speed limit, which can be used when calling DeleteTrafficInfo(). If aId is non-zero when passed in, it is used, and any existing object with that ID is replaced, otherwise a new identifier is generated.

aLine is a series of points defining the polygon. The polygon is calculated as the best route through the points, using the route network, so to be certain of specifying the desired polygon you need to supply a point for every junction.

aSpeed is the speed to which travel is restricted in kph. Values of zero or less indicate that the road is closed. Values higher than 255 indicate that there is no speed limit.

aVehicleTypes is a set of flags drawn from the constants in RouteProfile. If aVehicleTypes is 0, all vehicles are affected. Some useful values are RouteProfile.AllVehicles, RouteProfile.AllMotorVehicles and RouteProfile.BicycleAccessFlag.

A polygon map object representing the speed limit is added to the layer 'traffic'.

See also AddTrafficInfo(), AddLineSpeedLimit(), AddPolygonSpeedlimit(), AddForbiddenArea(), DeleteSpeedLimit(), and ClearTrafficInfo().

◆ AddForbiddenArea()

Result CartoType::Framework::AddForbiddenArea ( MapObjectId aId,
Geometry aPolygon 
)

Marks a certain polygon as forbidden for routing.

aId is used to return an identifier for the speed limit, which can be used when calling DeleteSpeedLimit(). If aId is non-zero when passed in, it is used, and any existing object with that ID is replaced, otherwise a new identifier is generated.

See also AddTrafficInfo, AddLineSpeedLimit(), AddPolygonSpeedLimit(), DeleteSpeedLimit() and ClearTrafficInfo().

◆ AddLineSpeedLimit()

Result CartoType::Framework::AddLineSpeedLimit ( MapObjectId aId,
Geometry aLine,
double  aSpeed,
int  aVehicleTypes 
)

Adds a speed limit in kph, to be used when calculating routes, to a route defined by a series of points.

aId is used to return an identifier for the speed limit, which can be used when calling DeleteTrafficInfo(). If aId is non-zero when passed in, it is used, and any existing object with that ID is replaced, otherwise a new identifier is generated.

aLine is a series of points defining the road. The road is calculated as the best route through the points, using the route network, so to be certain of specifying the desired route you need to supply a point for every junction. The points are snapped to the nearest nodes in the route network. This means that at the moment you cannot set a speed limit for a range smaller than an arc between two nodes.

aSpeed is the speed to which travel is restricted in kph. Values of zero or less indicate that the road is closed. Values higher than 255 indicate that there is no speed limit.

aVehicleTypes is a set of flags drawn from the constants in RouteProfile. If aVehicleTypes is 0, all vehicles are affected. Some useful values are RouteProfile.AllVehicles, RouteProfile.AllMotorVehicles and RouteProfile.BicycleAccessFlag.

A line map object representing the speed limit is added to the layer 'traffic'.

See also AddTrafficInfo(), AddClosedLineSpeedLimit(), AddPolygonSpeedlimit(), AddForbiddenArea(), DeleteSpeedLimit(), and ClearTrafficInfo().

◆ AddPolygonSpeedLimit()

Result CartoType::Framework::AddPolygonSpeedLimit ( MapObjectId aId,
Geometry aPolygon,
double  aSpeed,
int  aVehicleTypes 
)

Adds a speed limit in kph, to be used when calculating routes, to all roads in a certain polygon.

To specify particular roads, or an area enclosed by roads, use AddTrafficInfo(). This allows the router to take account of slow-downs caused by traffic density, road works, etc.

aId is used to return an identifier for the speed limit, which can be used when calling DeleteTrafficInfo(). If aId is non-zero when passed in, it is used, and any existing object with that ID is replaced, otherwise a new identifier is generated.

aSpeed is the speed to which travel is restricted, in kph. If aSpeed is zero or less, routing is forbidden in the given polygon.

aVehicleTypes is a set of flags drawn from the constants in RouteProfile. If aVehicleTypes is 0, all vehicles are affected. Some useful values are RouteProfile.AllVehicles, RouteProfile.AllMotorVehicles and RouteProfile.BicycleAccessFlag.

A polygon map object representing the speed limit is added to the layer 'traffic'.

See also AddTrafficInfo(), AddLineSpeedlimit(), AddForbiddenArea(), DeleteSpeedLimit(), and ClearTrafficInfo().

◆ AddProfile()

Result CartoType::Framework::AddProfile ( RouteProfile aProfile)

Adds a new routing profile.

A Framework object starts with a single routing profile. Adding new profiles allows several different routes to be calculated for the same start and end point.

This function has no effect if routing is performed on a map with a built-in contraction-hierarchy routing table (created using makemap /route=ch), because such a table is created using a fixed routing profile which can be set in makemap.

◆ AddTrafficInfo()

Result CartoType::Framework::AddTrafficInfo ( MapObjectId aId,
TrafficInfo aTrafficInfo,
LocationRef aLocationRef 
)

Adds traffic information, such as a speed restriction, prohibition on the use of a route, reduction in the number of lanes, notification of road works, etc. At present only speed restrictions are supported.

This is the general function. See also the specialized functions AddPolygonSpeedLimit, AddLineSpeedLimit(), AddClosedLineSpeedLimit() and AddForbiddenArea().

aId is used to return an identifier for the information, which can be used when calling DeleteTrafficInfo(). If aId is non-zero when passed in, it is used, and any existing object with that ID is replaced, otherwise a new identifier is generated.

aTrafficInfo gives the type of information (speed limit, etc.).

aLocationRef defines the location (area, road, point, etc.). Only the values ERoadOrientationForwards and ERoadOrientationNone (which means the same in this context) is supported for iRoadOrientation in aLocationRef.

◆ Area()

double CartoType::Framework::Area ( Geometry aGeometry)

Returns the area of a geometry object on the surface of the earth in square meters using the WGS84 ellipsoid.

The area of a point object is zero. The area of a line object is zero. This function ignores curves. All points are treated as on-curve.

◆ BuiltInProfile()

RouteProfile ^ CartoType::Framework::BuiltInProfile ( int  aIndex)

Returns a built-in routing profile selected by its index, or null if the index is out of range.

Routers allowing an arbitrary profile to be set have no built-in profiles. The contraction hierarchy router has one or more built-in profiles.

◆ ChooseRoute()

Result CartoType::Framework::ChooseRoute ( int  aRouteIndex)

Chooses one among a set of alternative routes.

The index aRouteIndex selects the route: index 0 is the route created from the standard profile set at the time of creating the CNavigator object. Indexes from 1 upwards select routes created using profiles added using AddProfile, in order of their addition.

Return ErrorNotFound if the index refers to a nonexistent route. Return ErrorNotNavigating if the framework is not navigating.

This function is most appropriately called after calling StartNavigation to create the routes, but before calling Navigate to supply a position.

◆ ClipBackgroundToMapBounds()

bool CartoType::Framework::ClipBackgroundToMapBounds ( bool  aEnable)

Enables or disables clipping the map background to the map bounds.

Use this when creating map tiles to be overlaid on a larger map, so that the background (sea) color does not erase the larger map's graphics. The return value is the previous state.

◆ ContourArea()

double CartoType::Framework::ContourArea ( Geometry aGeometry,
int  aContourIndex 
)

Returns the area of a geometry object on the surface of the earth in square meters using the WGS84 ellipsoid.

The area of a point object is zero. The area of a line object is zero. This function ignores curves. All points are treated as on-curve.

◆ ContourLength()

double CartoType::Framework::ContourLength ( Geometry aGeometry,
int  aContourIndex 
)

Returns the length of a geometry object on the surface of the earth in meters using the WGS84 ellipsoid.

The length of a point object is zero. This function ignores curves. All points are treated as on-curve.

◆ CreateBestRoute()

Route ^ CartoType::Framework::CreateBestRoute ( RouteProfile aProfile,
RouteCoordSet aCoordSet,
bool  aStartFixed,
bool  aEndFixed,
int  aIterations 
)

Creates an optimized route to visit a series of waypoints in any order.

If aStartFixed is true, the first point in the route is always the first point supplied. If aEndFixed is true, the last point in the route is always the last point supplied. To create a circular route starting and ending at a predetermined place, but visiting the other points in any order, set aStartFixed and aEndFixed true, and make the first and last point the same. aIterations is the number of different routes to be tried. If a value of zero or less is supplied, a small default number of iterations is used.

To use the route for navigation, call the UseRoute() function.

◆ CreateRouteFromXml()

Route ^ CartoType::Framework::CreateRouteFromXml ( RouteProfile aProfile,
String^  aFilenameOrData 
)

Creates a route by reading it from XML data in GPX or CartoType route format.

If the parameter aFileNameOrData starts with a less-than sign, it is treated as XML data, otherwise it is treated as a filename. If GPX data contains route elements, the first of them is used; otherwise the first track element is used if any. The profile is ignored if the data is in CartoType route format, which contains the profile used to create it.

◆ DeleteStyleSheet()

Result CartoType::Framework::DeleteStyleSheet ( int  aIndex)

Deletes the style sheet with the specified index.

The main style sheet (index 0) may not be deleted. Other style sheets have indexes from 1 up, in the order of loading.

◆ DeleteTrafficInfo()

Result CartoType::Framework::DeleteTrafficInfo ( int64_t  aId)

Deletes traffic information: a speed limit, forbidden area, or other information, referring to it by the ID returned when the restriction was added by AddTrafficInfo, AddLineSpeedLimit(), AddForbiddenArea(), etc.

Use ClearTrafficInfo() to delete all restrictions and forbidden areas.

◆ DisplayPositionOnNearestRoad()

Result CartoType::Framework::DisplayPositionOnNearestRoad ( double  aLong,
double  aLat,
double  aHeadingInDegrees,
NearestRoadInfo aInfo 
)

Moves the route position object and the route vector object to the nearest point on a road.

Uses the supplied position and heading and the current location match parameters. If aHeadingInDegrees is valid (not negative) use it to choose among roads going in different directions. If aInfo is non-null, return information about the nearest road. This function can be used whether or not navigation is being performed.

◆ DrawMemoryDataBase()

void CartoType::Framework::DrawMemoryDataBase ( bool  aEnable)

Enables or disables the drawing of the in-memory database when the rest of the map is drawn.

The in-memory database is used for the route, its start and end, and the current vehicle position. If drawing the in-memory database is disabled, you can get a separate image containing the objects from the in-memory database by calling MemoryDataBaseMapBitmap.

◆ EditInsertCurrentObject()

Result CartoType::Framework::EditInsertCurrentObject ( String^  aLayer,
MapObjectId aId,
bool  aReplace 
)

Inserts the currently edited object into a chosen layer.

Converts the curently edited object into an ordinary object. If aId is non-zero and aReplace is true, replaces any existing object with that ID, otherwise creates a new object. The ID of the new object is returned in aId.

◆ EditSelectNearestPoint()

Result CartoType::Framework::EditSelectNearestPoint ( double  aX,
double  aY,
double  aRadiusInMillimeters 
)

Selects an editable object by selecting the nearest point of any editable object within a given radius of (aX,aY), which is a point in display coordinates.

If the point is not within the given radius of an existing point, creates a new point.

◆ FindInDisplay()

Result CartoType::Framework::FindInDisplay ( MapObjectList aObjectList,
int  aMaxObjectCount,
double  aX,
double  aY,
double  aRadius 
)

Finds all objects within aRadius of the point aX,aY on the display.

The point and the radius are given in pixels. Unlike the other find functions, this function deals with the graphic representation of objects, so it will work correctly when the user clicks on an icon, but not on the actual location of the object represented by the icon.

◆ FindNearestRoad()

Result CartoType::Framework::FindNearestRoad ( NearestRoadInfo aInfo,
double  aX,
double  aY,
CoordType  aCoordType,
double  aHeadingInDegrees,
bool  aDisplayPosition 
)

Finds the nearest road to the point (aX,aY), returns information about it in aInfo, and optionally (if aDisplayPosition is true) sets the current location to that position. Uses the current location match parameters.

Roads are defined as routable map objects allowed by the current main route profile. If aHeadingInDegrees is valid (not negative) it is used to choose among roads going in different directions.

◆ FindPointsInPath()

Result CartoType::Framework::FindPointsInPath ( MapObjectList aObjectList,
Geometry aPath,
FindParam aFindParam 
)

Finds all point objects contained in a certain path.

To set parameters other than the path and the condition of finding points, pass a FindParam object with your chosen parameters.

◆ FindPolygonsContainingPath()

Result CartoType::Framework::FindPolygonsContainingPath ( MapObjectList aObjectList,
Geometry aPath,
FindParam aFindParam 
)

Finds all polygon objects containing a certain path.

To set parameters other than the path and the condition of finding polygons, pass a FindParam object with your chosen parameters.

◆ FindText()

Result CartoType::Framework::FindText ( MapObjectList aObjectList,
int  aMaxObjectCount,
String^  aText,
StringMatchMethod  aMatchMethod,
String^  aLayers,
String^  aAttrib 
)

Finds objects with attributes matching aText.

If aLayers is null or empty, searches all layers, otherwise aLayers is a list of layers separated by spaces or commas. If aAttributes is null or empty, searches all attributes, otherwise aAttributes is a list of attributes separated by spaces or commas; use "$" to indicate the label (the unnamed attribute).

◆ GeoCodeSummary() [1/2]

String ^ CartoType::Framework::GeoCodeSummary ( double  aX,
double  aY,
CoordType  aCoordType 
)

Returns a string summarizing a geocode for a geographical location.

The summary is a string version of the address returned by GetAddress.

Calls to this function are limited in number in unlicensed (evaluation) versions of the CartoType library.

◆ GeoCodeSummary() [2/2]

String ^ CartoType::Framework::GeoCodeSummary ( MapObject aMapObject)

Returns a string summarizing a geocode for a map object.

The summary is a string version of the address returned by Address.

Calls to this function are limited in number in unlicensed (evaluation) versions of the CartoType library.

◆ GetAddress() [1/2]

Result CartoType::Framework::GetAddress ( Address aAddress,
double  aX,
double  aY,
CoordType  aCoordType 
)

Creates an address for a point in the map.

Calls to this function are limited in number in unlicensed (evaluation) versions of the CartoType library.

◆ GetAddress() [2/2]

Result CartoType::Framework::GetAddress ( Address aAddress,
MapObject aMapObject 
)

Creates an address for a map object.

Calls to this function are limited in number in unlicensed (evaluation) versions of the CartoType library.

◆ Height()

int CartoType::Framework::Height ( double  aX,
double  aY,
CoordType  aCoordType 
)

Returns the height in metres at a single point, or -32768 if it is unavailable.

The layer 'terrain-height-metres' is used by preference. It contains heights to metre precision. If that layer is not available, the layer 'terrain-height-feet' is used, which contains heights to 100-foot precision.

◆ InsertCircleMapObject()

Result CartoType::Framework::InsertCircleMapObject ( int  aMapHandle,
String^  aLayerName,
double  aCenterX,
double  aCenterY,
CoordType  aCenterCoordType,
double  aRadius,
CoordType  aRadiusCoordType,
String^  aStringAttributes,
FeatureInfo aFeatureInfo,
MapObjectId aId,
bool  aReplace 
)

Inserts a circle map object into one of the maps, identifying the map by its handle. If aMapHandle is zero the in-memory map used for routing is used.

If aFeatureInfo is null the default feature info is used (unknown non-route). The circle is defined by its center and radius, which may be in different coordinate systems. It is often convenient to supply a point in degrees long/lat and its radius in map meters. Uses the supplied ID if aId is non-null, otherwise generates an ID. Returns the ID in aId. This function fails if the map is not writable.

◆ InsertCopyOfMapObject()

Result CartoType::Framework::InsertCopyOfMapObject ( int  aMapHandle,
String^  aLayerName,
MapObject aObject,
double  aEnvelopeRadius,
CoordType  aRadiusCoordType,
MapObjectId aId,
bool  aReplace 
)

Inserts an object by copying an existing object.

If aEnvelopeRadius is greater than zero, convert the object to an envelope using the specified radius. Use the supplied ID if aId is non-zero, otherwise generate an ID. Return the ID in aId. This function fails if the map is not writable.

◆ InsertEllipseMapObject()

Result CartoType::Framework::InsertEllipseMapObject ( int  aMapHandle,
String^  aLayerName,
double  aCenterX,
double  aCenterY,
CoordType  aCenterCoordType,
double  aRadiusX,
double  aRadiusY,
CoordType  aRadiusCoordType,
double  aRotationDegrees,
String^  aStringAttributes,
FeatureInfo aFeatureInfo,
MapObjectId aId,
bool  aReplace 
)

Inserts an ellipse map object into one of the maps, identifying the map by its handle. If aMapHandle is zero the in-memory map used for routing is used.

If aFeatureInfo is null the default feature info is used (unknown non-route). The ellipse is defined by its center and radii, which may be in different coordinate systems, and its rotation in degrees. It is often convenient to supply a point in degrees long/lat and radii in map meters. Uses the supplied ID if aId is non-null, otherwise generates an ID. Returns the ID in aId. This function fails if the map is not writable.

◆ InsertEnvelopeMapObject()

Result CartoType::Framework::InsertEnvelopeMapObject ( int  aMapHandle,
String^  aLayerName,
Geometry aGeometry,
double  aRadius,
CoordType  aRadiusCoordType,
String^  aStringAttributes,
FeatureInfo aFeatureInfo,
MapObjectId aId,
bool  aReplace 
)

Inserts a map object that is an envelope around some geometry, at a radius of aRadius; it can also be regarded as a stroke drawn along the path with a stroke width of twice aRadius.

The geometry and the radius may use different coordinate systems. It is often convenient to supply the geometry in degrees long/lat and its radius in map meters. If aFeatureInfo is null the default feature is used (unknown non-route). Uses the supplied ID if aId is non-zero, otherwise generates an ID. Returns the ID in aId. This function fails if the map database is not writable.

◆ InsertMapObject()

Result CartoType::Framework::InsertMapObject ( int  aMapHandle,
String^  aLayerName,
Geometry aGeometry,
String^  aStringAttributes,
FeatureInfo aFeatureInfo,
MapObjectId aId,
bool  aReplace 
)

Inserts a map object into one of the writable maps. The type of the map object (point, line or polygon) is deduced from the geometry object. If aMapHandle is zero the in-memory map used for routing is used.

If aFeatureInfo is null the default feature info is used (unknown non-route). Uses the supplied ID if aId is non-zero, otherwise generates an ID and returns it in aId. This function fails if the map is not writable.

◆ InsertPointMapObject()

Result CartoType::Framework::InsertPointMapObject ( int  aMapHandle,
String^  aLayerName,
double  aX,
double  aY,
CoordType  aCoordType,
String^  aStringAttributes,
FeatureInfo aFeatureInfo,
MapObjectId aId,
bool  aReplace 
)

Inserts a point object into one of the writable maps, identifying it by its handle. If aMapHandle is zero the in-memory map used for routing is used.

If aFeatureInfo is null the default feature info is used (unknown non-route). Uses the supplied ID if aId is non-zero, otherwise generates an ID. Returns the ID in aId. This function fails if the map is not writable.

◆ InsertPushPin()

Result CartoType::Framework::InsertPushPin ( double  aX,
double  aY,
CoordType  aCoordType,
String^  aStringAttributes,
String^  aColor,
int  aIconCharacter,
MapObjectId aId 
)

Inserts a pushpin: a point object belonging to the 'pushpin' layer. The pushpin is inserted into the built-in modifiable map.

If aColor is not empty it is used as the _color attribute, which, in the standard style sheet, causes the pushpin icon to be drawn in that color instead of the standard color.

If aIconCharacter is not zero it is used to set the _iconText attributes, which, in the standard style sheet, causes that character to be used as an icon. The MapKeyIcons font is supplied with CartoType and contains icons in the private-character range U+E002...U+E0B1.

If aId is zero, a new pushpin is inserted and its ID is returned in aId. If aId is non-zero, an existing pushpin with the specified ID, if any exists, is replaced.

◆ Length()

double CartoType::Framework::Length ( Geometry aGeometry)

Returns the length of a geometry object on the surface of the earth in meters using the WGS84 ellipsoid.

The length of a point object is zero. This function ignores curves. All points are treated as on-curve.

◆ LoadIcon()

Result CartoType::Framework::LoadIcon ( String^  aFileName,
String^  aId,
int  aHotSpotX,
int  aHotSpotY,
int  aLabelX,
int  aLabelY 
)

Loads an icon from a file. It will be used whenever the ID aId is referenced in the style sheet, overriding any icon specified in the style sheet.

The icon file may be in PNG or JPEG format.

(aHotSpotX,aHotSpotY) is the point, relative to the top left corner of the icon, that should be made to coincide with the point of interest marked by the icon.

(aLabelX,aLabelY) is the point, relative to the hot spot, at which the center of the baseline of any label text is placed.

◆ LoadNavigationData()

Result CartoType::Framework::LoadNavigationData ( )

Loads navigation data for the current map.

This function need not be called; if it is not called, navigation data will be loaded automatically when it is first needed. It is provided so that the time overhead of loading navigation data can be incurred at a predictable stage, for example at application startup.

No error is returned if navigation data has already been loaded.

By default, serialized navigation data is used. That behavior can be changed by calling UseSerializedNavigationData.

◆ MutuallyAccessible()

bool CartoType::Framework::MutuallyAccessible ( IVector< PointValue >^  aPointArray,
CoordType  aCoordType,
IVector< int >^  aGroupArray 
)

Determines the mutual accessibility of a set of points for routing purposes, using the current routing profile. This function is implemented only for the turn-expanded router.

If aGroupArray is non-null it is filled with the connectivity group IDs of the points. A set of points that is mutually accessible will have identical non-zero group IDs. A group ID of zero indicates that a point is not near enough to a road or other routable segment. Group IDs are ordered by group sizes. Group 1 is the group with the largest number of connected route nodes, therefore in general a point needs to be in group 1 to take part in routing.

◆ Navigate()

Result CartoType::Framework::Navigate ( int  aValidity,
double  aTime,
double  aLong,
double  aLat,
double  aSpeed,
double  aBearing,
double  aHeight 
)

Updates the vehicle position and, if navigating, updates the navigation state.

In order to implement turn-by-turn navigation, you should call Navigate() at frequent intervals (once per second is good enough) after creating a route using StartNavigation(), ReadRouteFromXml(), etc.

When not navigating, you may call this function to update the vehicle position if necessary (i.e., if the current follow mode displays the vehicle position: see SetFollowMode()).

aValidity is a set of bit flags, ORed together, which determines which of the other parameters are valid. The bit flags are the constants ValidityFlag.Time, ValidityFlag.Position, etc. For normal navigation not all the data is necessary: you need supply the time and position only. Other data, if available, helps the navigation system decide which road the vehicle is on, and extrapolate positions. The height (elevation above sea level) is not currently used.

aTime is the time in seconds. Any consistent time representation may be used (e.g., the unix timestamp format of the time in seconds since midnight, 1st Jan 1970); the absolute time does not matter as long as times can be subtracted to give a difference in seconds.

aLong and aLat are the location in degrees longitude and latitude, using the WGS84 datum.

aSpeed is the speed in kilometres per hour.

aBearing is the true course in degrees, where 0 is north, and degrees increase clockwise; 90 is east, 180 is south, and 270 is west.

aHeight is the height above sea level in metres.

If the position is invalid, Navigate() guesses the position by extrapolating from the current speed, if known, and the previous position.

After Navigate() has been called, the map position, rotation or zoom will change according to the current follow mode (see SetFollowMode()).

If you are not using graphics acceleration you should redraw the map after calling this function.

◆ Range()

Geometry ^ CartoType::Framework::Range ( RouteProfile aProfile,
double  aX,
double  aY,
CoordType  aCoordType,
double  aTimeOrDistance,
bool  aIsTime 
)

Returns the range: a polygon containing the area reachable within a certain time in seconds or distance in meters.

Uses the supplied route profile if it is non-null, otherwise the current profile. If a time is supplied, the profile's bonuses and penalties are suppressed. If a distance is supplied, shortest routes are used. You can optionally insert the returned Geometry object into the map using InsertMapObject.

◆ ReadGpx()

Result CartoType::Framework::ReadGpx ( int  aMapHandle,
String^  aFileName 
)

Reads route and track objects from a GPX file and inserts them into the map identified by aMapHandle. This function fails if the map is not writable.

Waypoint objects (wpt) are made into points in the gpx/wpt layer. Route objects (rte) are made into lines in the gpx/rte layer. Track objects (trk) are made into lines in the gpx/trk layer.

◆ ReadRouteFromXml()

Result CartoType::Framework::ReadRouteFromXml ( String^  aFileNameOrData,
bool  aReplace 
)

Reads a route from XML (a GPX file or a CartoType route file) and displays it.

aFileNameOrData is treated as XML data if it starts with a less-than sign.

If aReplace is true, delete all current routes, add the new route and make its profile the current profile. If aReplace is false, append the new route to the list of current routes.

Appending a route fails if the new route has a different start and end point, or intermediate waypoints, from the current routes.

This function resets the navigation state and enables navigation.

◆ ReloadStyleSheet()

Result CartoType::Framework::ReloadStyleSheet ( int  aIndex)

Reloads a sheet from the file it was originally loaded from.

This function can be used to apply changes after a style sheet is modified. The index aIndex determines which style sheet is reloaded: 0 means the main style sheet, and numbers from 1 up refer to extra style sheets. Only style sheets loaded from files can be reloaded.

◆ SetBuiltInProfile()

Result CartoType::Framework::SetBuiltInProfile ( int  aIndex)

Selects a built-in routing profile by its index.

Routers allowing an arbitrary profile to be set have no built-in profiles. The contraction hierarchy router has one or more built-in profiles.

◆ SetCase()

String ^ CartoType::Framework::SetCase ( String^  aString,
LetterCase  aCase 
)

Sets the letter case of a string.

Supports all UTF-16 characters. Uses the title-case exception dictionary to prevent words like 'of' being capitalised. Returns the modified string. Does not change aString.

◆ SetMainProfile()

Result CartoType::Framework::SetMainProfile ( RouteProfile aProfile)

Sets the main routing profile.

If you do not call this function, the standard profile for private car routing is used.

This function has no effect if routing is performed on a map with a built-in contraction-hierarchy routing table (created using makemap /route=ch), because such a table is created using one or more fixed routing profiles which can be set in makemap. Use SetBuiltInProfile for contraction hierarchy routing.

◆ SetNearbyObjectWarning()

int CartoType::Framework::SetNearbyObjectWarning ( int  aId,
String^  aLayer,
String^  aCondition,
double  aMaxDistance,
int  aMaxObjectCount 
)

Adds or replaces a nearby object warning.

Objects found are added to the 'nearby' layer while the warning is in force. The attribute '_warning=0' is set.

Objects in aLayer, satisfying aCondition if it is not empty, and within aMaxDistance of the current point, are highlighted. The parameter aLayer may contain wild cards or end in a '/' sign.

The parameter aMaxObjectCount is the maximum number of objects to be found, which is clamped to the range 0...1024. If it is zero, the default of 32 is used. If more objects are actually found, the closest ones are used.

If aId is zero, a new warning is created. If aId is non-zero, the existing warning if any with an ID of aId is replaced. The ID of the new or replaced warning is returned. If aMaxDistance, which is in meters, is less than or equal to zero, it is set to the default distance of 1000, or 1km.

Returns 0 if no warning was created, which occurs if aLayer was empty, or the navigation system could not be created.

◆ SetStyleSheetData()

Result CartoType::Framework::SetStyleSheetData ( String^  aData,
int  aIndex 
)

Sets a style sheet by loading it from data in memory.

The index aIndex determines which style sheet to replace: 0 means the main style sheet, and numbers from 1 up refer to extra style sheets.

◆ SetTileOverSizeZoomLevels()

int CartoType::Framework::SetTileOverSizeZoomLevels ( int  aLevels)

Sets the number of zoom levels by which to zoom out when creating a tile bitmap returned by TileBitmap().

The number may be 0, 1, or 2. If it is 0, each tile is self-contained. If it is 1, each tile is cut from a larger tile containing four tiles. If it is 2, each tile is cut from a larger tile containing sixteen tiles. The values 1 and 2 are useful in allowing longer labels to be used when creating small tiles; if not, many street labels will not be drawn because the street is cut in two by the tile border and the resulting sections are too short.

Returns the previous number of levels.

◆ SetTurnInstructionText()

void CartoType::Framework::SetTurnInstructionText ( String^  aText)

Sets the instruction to be displayed for the current turn, overriding automatically generated instructions.

To revert to automatically generated instructions, call this function with empty or null text. This function has no effect if turn instructions have not been created using SetTurnInstructions, or have been disabled by calling EnableTurnInstructions(false).

◆ SetVehicleTypeWarning()

int CartoType::Framework::SetVehicleTypeWarning ( double  aMaxDistance,
int  aMaxObjectCount 
)

Adds a vehicle type warning and returns its ID. Road sections illegal for the current vehicle weight, dimensions or cargo type are found.

Objects found are added to the 'nearby' layer while the warning is in force. The attribute '_warning=1' is set.

The parameter aMaxObjectCount is the maximum number of objects to be found, which is clamped to the range 0...1024. If it is zero, the default of 32 is used. If more objects are actually found, the closest ones are used.

If there is already a vehicle type warning it is replaced by this one.

Returns 0 if no warning was created, which occurs if aLayer was empty, or the navigation system could not be created.

◆ SetViewLimits()

Result CartoType::Framework::SetViewLimits ( double  aMinScaleDenominator,
double  aMaxScaleDenominator,
Geometry aPanArea 
)

Sets the limits to zooming and panning.

Zooming is restricted to the range between aMinScaleDenominator and aMaxScaleDenominator, and panning is restricted so that the edges of the display always touch the bounds of aPanArea.

Use the value zero to remove either or both of the two zoom limits. Use an empty (not null) geometry object to remove panning limits. Use a null geometry object to limit panning to the extent of the map.

◆ TimeAndDistanceMatrix()

TimeAndDistanceMatrix ^ CartoType::Framework::TimeAndDistanceMatrix ( IVector< PointValue >^  aFrom,
IVector< PointValue >^  aTo,
CoordType  aCoordType 
)

Returns a vector of route times in seconds and distances in metres from aFrom to all points in aTo.

If routing fails for any pair of points the time and distance are set to UINT32_MAX. It is legal for aFrom to refer to the same vector as aTo. Times and distances where the start and end point are the same are set to zero. The returned vector contains (F * T * 2) entries, where F and T are the sizes of aFrom and aTo. The time for the route from aFrom[i] to aTo[j] is in entry (i * T * 2 + j) and the distance is in entry (i * T * 2 + j + 1).

◆ UseRoute()

Result CartoType::Framework::UseRoute ( Route aRoute,
bool  aReplace 
)

Use an existing route and display it.

If aReplace is true, delete all current routes and add the new route. If aReplace is false, append the new route to the list of current routes.

Appending a route fails if the new route has a different start and end point, or intermediate waypoints, from the current routes.

This function resets the navigation state.

◆ ZoomAt()

Result CartoType::Framework::ZoomAt ( double  aZoomFactor,
double  aX,
double  aY,
CoordType  aCoordType 
)

Zooms in by a specified zoom factor, or zooms out if the zoom factor is less than 1, centering the zoom at the specified position, so that it remains at the same place on the display.

This function does not zoom in beyond the minimum scale denominator (1:500) or zoom out beyond the maximum scale denominator (1:1,000,000,000) or beyond a size where the map occupies the whole display.

Property Documentation

◆ ActualRouterType

RouterType CartoType::Framework::ActualRouterType
get

The actual router type.

If route data has been loaded for the current map or maps, returns the actual router type in use, which may not be the same as the preferred router type, because some router types are not available for certain types of data.

If the route data has not been loaded, returns RouterType.Default. Route data is loaded either when the first route is constructed, or when LoadNavigationData is called.

◆ BlendStyleSet

BlendStyleSet^ CartoType::Framework::BlendStyleSet
getset

The blend style. To remove the current blend style, set it to null or empty.

If night mode is on, night mode is turned off and replaced by the specified blend style or by no blend style.

◆ BuiltInProfileCount

int CartoType::Framework::BuiltInProfileCount
get

Returns the number of built-in routing profiles owned by the router.

This function returns zero for routers allowing an arbitrary profile to be set, and one or greater for the contraction hierarchy router, which stores one or more fixed profiles.

◆ ContinuationTurn

Turn^ CartoType::Framework::ContinuationTurn
get

The continuation turn during navigation.

The continuation turn, if non-any, signals that there is an 'ahead' or 'continue' turn before the first turn, so that the navigation system can show that no turn is required at the next junction or adjoining minor road. Its m_distance member is the distance from the current position to the continuation turn.

◆ FirstTurn

Turn^ CartoType::Framework::FirstTurn
get

The first turn during navigation.

The first turn is the first significant turn after the current position, ignoring 'ahead' and 'continue' turns. If its type is None there are no remaining significant turns. Its m_distance member is the distance from the current position to the first turn or the arrival point.

◆ FixedLabels

bool CartoType::Framework::FixedLabels
getset

True if labels are drawn, as far as possible, in fixed positions, and not moved when the map is panned.

*‍/

◆ LocationMatchParam

LocationMatchParam^ CartoType::Framework::LocationMatchParam
getset

The current location match parameters.

These parameters are used when creating routes in functions which do not receive explicit location match parameters. In functions which do receive location match parameters, any parameters with the value 0 are replaced by the current location match parameters set by this function.

◆ NightModeColor

Color CartoType::Framework::NightModeColor
getset

The night mode color, which should be a dark color (although this is not enforced).

To set a custom blend fraction, use the alpha value. For example, set the color's alpha value to 153 to blend the night mode color with a style color in the ratio 0.6 : 0.4 (153/255 = 0.6). Use an alpha value of 255 to get the default blend fraction.

Roads use the night mode color blended with 50% white, and half the specified blend fraction. This increases contrast between roads and other features.

◆ PreferredRouterType

RouterType CartoType::Framework::PreferredRouterType
getset

The preferred type of router to be used for calculating routes.

Different routers have various advantages and disadvantages, such as using more or less memory, being faster or slower, or producing more useful routes.

Setting the preferred router type causes navigation data to be unloaded if the current navigation data uses a different type of router.

◆ SecondTurn

Turn^ CartoType::Framework::SecondTurn
get

The second turn during navigation.

The second turn, if any, indicates that there is a significant turn 100 metres or less after the first turn. Its m_distance member is the distance from the first turn to the second turn.


The documentation for this class was generated from the following file: