Basic MapLink Applications

At its simplest level, the MapLink Core SDK can be summarised in three concepts and two sentences.

• Data is loaded into Layers.

• Layers are displayed on Drawing Surfaces.

Of course you’ll probably need more detailed information before you design your application, and this section is intended to give you that information.

Application Architecture

MapLink has almost unparalleled flexibility amongst GIS components. At the heart of this lies the fact that MapLink is essentially passive. It does not create any windows, nor trap any events. The drawback of this design decision is that you need to add a few extra lines to your code. The benefit is that you don’t have to design the rest of your application around MapLink - it will bend to fit into whatever architecture is most suited to your problem domain.

The Document/View Model

The document can be thought of as a MapLink Data Layer, or more likely, a set of Data Layers. The Core SDK contains several specialisations of the base Data Layer, each capable of displaying different types of data. The most common is the TSLMapDataLayer. This manages and displays maps that have been generated by MapLink Studio. Another common Data Layer is the TSLStandardDataLayer. This is typically used to display simple vector overlays but can also be utilised by the Editor SDK for complex interactive drawing.

The View concept maps directly onto the MapLink TSLDrawingSurface. In the same way that a View is a visualisation of a Document, a TSLDrawingSurface visualises a set of TSLDataLayer’s that have been attached to it. As described above, MapLink is passive, so relevant events should be managed by the application and passed onto MapLink.

For simple applications that merely visualise data, MapLink will only be interested in the initialisation, resize and paint events. These should generally be passed onto the TSLDrawingSurface. More complex applications that use the Editor SDK may also need to pass mouse events onto the TSLEditor class.

A Data Layer may be displayed in many different Drawing Surfaces, and a Drawing Surface may display many different Data Layers. Each Drawing Surface is independent of the others and may display a different part of the Data Layer or be at a different zoom level.

Error Handling

In keeping with its passive nature, MapLink will not interrupt your application by throwing exceptions or bringing up an error dialog. Instead, it maintains an internal stack of errors that have occurred and returns a failure status from those methods that fail. The error stack may be accessed through the TSLThreadedErrorStack utility class. (This class is a thread-safe version of the TSLErrorStack class which it supersedes). TSLErrorStack is retained for backwards compatibility purposes but its use is discouraged. .NET users have the TSLNErrorStack class, which is a wrapper around the TSLThreadedErrorStack class, for provision of thread-safe access to the stack.

Error reports on the error stack are encoded in an error number with an associated string to provide further information, such as a filename. Some pre-processor constants and descriptive comments for each error are defined in header files supplied with the MapLink Core SDK. These are the ‘*err.h’ files in the include directory. These allow the application to identify the error that has occurred and handle it in a graceful manner.

Error Messages

The Error message strings are stored as a series of message files, which are contained in the config directory, all having a ‘msg’ file ending. Only the primary message string is contained in these files. Additional information may be generated by the SDK when an error occurs.

The controlling message file is ‘allmaplinkerrors.msg’. This file will only be loaded when the developer requests textual information on the Error.

The ‘msg’ files only provide additional information, so if they do not exist, then MapLink will provide basic information. The controlling message file can also be trimmed to reduce the loaded message strings.

Typically you may exclude the ‘msg’ files when memory is at a premium.

View and Interaction Modes

Most applications will require some sort of navigation controls such as pan and zoom. To assist with the implementation of these, Envitia supply a suite of useful interaction modes in source code form. The Windows MapLink samples provide the relevant source code, which can be easily incorporated into your own application and modified to suit your requirements.

Coordinates and Positions

MapLink uses several different types of coordinate storage. These are optimised for particular uses.

Map Units (MU) are the basic Cartesian units generated by the Coordinate System applied to a map within MapLink Studio. These are dependent upon the transformations applied but are generally mapped to nominal metres in the chosen map coordinate system. The origin of this coordinate space is typically the centre of the map projection that has been applied, modified by any false easting and northing.

Related to Map Units, User Units are available through the Core SDK. They are simply scaled and offset versions of Map Units. Thus, if Map Units were in metres, a User Unit scale of 1000 could be applied so that the map may be referenced in kilometres. Likewise, the origin could be offset to the centre of the map space, the lower left corner or some other user-defined position. The current view of a Drawing Surface is generally specified in terms of User Units.

Latitude and Longitude are typically used for real world positions. It is important to note that latitude/longitude coordinates are in themselves of no value since they are only applicable to a particular reference datum. In MapLink, this is assumed by default to be the reference datum of the map’s Output Coordinate System. A flag on the conversion functions allows this to be referenced via WGS84 instead. The Drawing Surface contains methods that allow the current view to be set by specifying a latitude/longitude position and a range in map units. This is particularly useful when using the Dynamic Projection capabilities of MapLink, since the underlying Coordinate System, and hence the Map Unit scale and origin may change.

TMC units are the internal integer units that MapLink uses to store its geometry. These are independent of map and Drawing Surface and are used to create new geometric primitives.

Device Units are the reference system of the output display device that a Drawing Surface is attached to. These will typically be pixels, but under some circumstances, such as MFC Print Preview, these are modified to represent some other device.

The Drawing Surface and Map Data Layer classes contain methods for conversion between these various coordinate systems.

Configuration Data

MapLink holds style information in various configuration files. These configuration files provide a mapping between internal styles or colour ID’s and their visualisations.

Standard configuration files for line-styles, fill-styles, fonts, symbols and colours are provided in the installed MapLink config directory. When a style is attached to a Feature Class or to an Entity, it stores the style ID. The run-time rendering engine looks up the ID in the currently loaded style list.

The configuration data is held statically so usually need only be loaded once per application run. The exception to this is the colours file. This is held statically but may need to be reloaded to match the palette for a particular map. This means that if multiple maps are displayed in a single application then they must be created using the same palette.

Map Display using TSLMapDataLayer

The TSLMapDataLayer object manages the display of a Map that has been produced by MapLink Studio. These Maps consist of several configuration files and a set of vector or raster tiles. The TSLMapDataLayer maintains a configurable memory cache of tiles and an optional, configurable disk cache of tiles. The latter is often used for remote or Internet based systems.

As described in the MapLink Studio documentation, a map can consist of several detail layers, each usually representing a particular area of interest at a particular level of detail or zoom with further optimisation available through tiling. A TSLMapDataLayer will automatically choose the appropriate detail layer according to configuration parameters set in MapLink Studio. Once a detail layer is chosen, the TSLMapDataLayer will manage the loading and caching of relevant tiles. This is the default behaviour. For specific requirements, the Data Layer can be forced to display a particular detail layer as long as the automatic detail layer selection is disabled.