CartoType release 4.0
and how it differs from release 3
Changes affecting all APIs
The Legend API
The new Legend API allows you to create consistent, good-looking and flexible legends (scale bars and keys to symbols) as separate images which can be overlaid on the map or drawn elsewhere.
Consistent argument order for the Find functions
The many Find functions now order their arguments consistently. The destination array always comes first, followed by the maximum object count if applicable, and so on. These changes also affect the non-C++ APIs.
C++
Moving to C++11
The main theme of the changes is a move to modern C++. C++11 is supported on all major platforms, including Windows (VS2015), iOS (Xcode), the Android NDK (gcc), and Linux (gcc).
Memory allocation failure throws an exception
CartoType's builds formerly disabled exceptions and handled out-of-memory conditions by using a memory allocator which returned null when out of memory. The error KErrorNoMemory was then propagated back up the stack. CartoType 4.0 uses exceptions, and throws std::bad_alloc when an allocation fails. Other errors like failing to open a file are still handled using error codes.
Arrays are std::vector objects
CartoType's main two array classes are now publicly derived from std::vector:
template<class T> class CArray: public std::vector<T>
template<class T> class CPointerArray: public std::vector<T*>
That means you can now use all the std::vector functions and algorithms. Of course, because memory allocation failure now throws an exception, array functions no longer return error codes.
Sample code showing the use of range for with a CartoType array:
CPointerArray<CBaseMapObject> found_objects;
my_framework->Find(found_objects,find_param);
for (const auto p : found_objects)
{
size_t everywhere
Many argument and return types have changed from int32 to size_t to avoid warnings when using the new array classes based on std::vector.
CString
CartoType::CString now has value semantics, which means you can assign strings to each other, pass them as function arguments, return them from functions, and create arrays of them. A CString still holds UTF-16 text, but can now be constructed from null-terminated 8-bit strings, and also from std::string. You can even construct a string from nullptr, which makes it easy to have default CString arguments: void myfunc(CString aText = nullptr). All this means that…
String arguments are simpler
Most functions taking string arguments now take CString or const CString&. Overloads taking const char* no longer exist. But thanks to the new CString constructors you can pass 8-bit string literals or std::string objects if you like.
So you can call CFramework::LoadMap in these different ways:
my_framework->LoadMap("england.ctm1");
std::string map_name1("wales.ctm1");
my_framework->LoadMap(map_name1);
CString map_name2("scotland.ctm1");
my_framework->LoadMap(map_name2);
Observer interface: MFrameworkObserver
The new observer interface allows you to provide an observer object to a CartoType::CFramework object. The observer receives notifications of changes to the framework state. It is intended for the use of higher-level GUI objects which need to update their display after framework state has been changed programmatically. For example, if a route is created, dynamic map objects need to be redrawn.
British national grid functions
There are some new functions to convert back and forth between British national grid references and other position formats. They are useful when comparing CartoType maps of Great Britain with Ordnance Survey maps.
CT_IMPORT and CT_EXPORT have gone
The macros CT_IMPORT and CT_EXPORT were used in older versions of CartoType to declare functions as exported from DLLs. The C++ SDK is no longer built or shipped as a DLL, therefore these macros have been abolished.
Simpler functions to set and get string attributes
The functions to set and get string attributes have been simplified. For example, where you formerly wrote:
CString key; key.Set("addr:street");
TText street;
my_map_object->GetStringAttribute(&key,street);
you can now write
CString street = my_map_object->GetStringAttribute("addr:street");
The makemap tool
No more support for old-style import scripts
Two obsolete import script formats are no longer supported. They are the old OSM rule format with the extension .osm_to_ctm1_rules, and the old shapefile rule format with the extension xml. The new .makemap format replaces them both.
In particular, when you import coastlines from shapefile data you should use a coastlines.makemap file with this content (adjusting the filename as necessary):
<?xml version="1.0" encoding="UTF-8"?>
<CartoTypeImportRules>
<file name='\coastlines-complete\land_polygons.shp'>
<commit layer='outline'/>
</file>
</CartoTypeImportRules>
The .makemap import rules format is described here: http://www.cartotype.com/import-rules-used-by-makemap.html .