Inheritance diagram for TSLDrawingSurface:

[legend]

Detailed Description

Passive component for displaying 2D data to a user supplied window.

The TSLDrawingSurface component is responsible for the display of 2D data in a window supplied by the end user. As the TSLDrawingSurface is passive, there are no inherent event handling routines.

This component provides the following capabilities

Drawing and view methods
Coordinate Conversions
Miscellaneous methods

Other capabilities such as feature rendering, decluttering and style queries are provided by the base TSLDrawingSurfaceBase class and the derived platform specific classes.

A TSLDrawingSurface must be connected to a user-supplied window (or HDC/Pixmap) before it can display anything. It does not create a window of its own. This gives the user control over what is displayed in the window.

A TSLDrawingSurface will display 2D data from any data layers that are connected to it. Layer control is handled by the TSLDrawingSurfaceBase class.

The area of data displayed by the TSLDrawingSurface can be modified by the methods 'zoom' and 'pan'. These methods take user-unit parameters and attempt to maintain the aspect ratio of the view. To redraw a specific area on the TSLDrawingSurface, two 'draw...' methods are available. The user must inform the TSLDrawingSurface of any modifications to the window size (in pixels) using the method 'wndResize' so that the TSLDrawingSurface can correctly calculate the area to display in the window.

The user has an alternative method of changing the area displayed by the TSLDrawingSurface by calling 'resize'. This informs the TSLDrawingSurface of the complete world co-ordinate area to display. The image displayed by the drawing surface may be rotated by the 'rotate' method. This does not alter the raw data, only the way it is displayed on screen. Note that at present, Raster data cannot be rotated by MapLink.

Various methods are also available to set up user units, convert from internal TMC co-ordinate units to user units and vice versa. Line styles, fill styles, symbol styles, colors and fonts are loaded by the TSLDrawingSurface from a file by calling 'loadStandardConfig' or by individual calls to 'setupLineStyles', 'setupFillStyles', 'setupSymbols', 'setupColours' and 'setupFonts'. These methods are static should only be called once by the application. To free the memory associated with these configurations, the 'cleanup' static method should be called when an application finishes. References to single styles take the form of an index into the list of styles loaded.

TSLDrawingSurface provides mapping between 4 co-ordinate spaces:

MapLink Mapping Co-ordinate (TMC). This is the internal representation of the map data co-ordinate space.
Map unit. This is the co-ordinate space of the map. For example, if a projection has been applied to the map, the map units may be metres, whereas if no projection or transformation has been applied the map units are directly mapped to the co-ordinate space of the input data set.
User unit. This is a scaled version of the map units, so that the user can choose the unit he will work with. For example, if the map units is metres, a user unit scaling factor of 1000 can be applied allowing the user to work in kilometres.
Device unit: co-ordinate space of the display device (usually pixel).

This class is an abstract class, specifying the generic behaviour of a 2D TSLDrawingSurface.

Public Member Functions
bool	clearAllRendering ()

bool	clearDynamicColours ()

virtual TSLDrawingSurface *	clone (bool copyUserData=false)=0

TSLRasterBuffer *	createRasterBuffer (unsigned int width, unsigned int height, TSLRasterBuffer::Format format, TSLRasterBuffer::FilterMode filterMode=TSLRasterBuffer::Linear)

bool	declutterIsVisible (const char feature_name, double resolution=0.0, const char layer_name=0) const

bool	drawDU (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool clear, bool updateExtentOnly=false)

bool	drawUU (double x1, double y1, double x2, double y2, bool clear, bool updateExtentOnly=false)

bool	DUToLatLong (TSLDeviceUnits x, TSLDeviceUnits y, double latitude, double longitude, bool local=false, bool boundCheck=true) const

bool	DUToMU (TSLDeviceUnits x1, TSLDeviceUnits y1, double x2, double y2) const

bool	DUToTMC (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLTMC x2, TSLTMC y2) const

bool	DUToUU (TSLDeviceUnits x1, TSLDeviceUnits y1, double x2, double y2) const

TSLEntity *	findEntityDU (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, const char *feature_name=NULL)

TSLEntity *	findEntityUU (double x, double y, double aperture, int depth, const char *feature_name=NULL)

TSLEntity *	findSelectedEntityDU (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, bool ignoreMapDataLayers=false)

TSLEntity *	findSelectedEntityUU (double x, double y, double aperture, int depth=-1, bool ignoreMapDataLayers=false)

bool	getColourIndices (int *indices, int num)

TSLDataLayer *	getCoordinateProvidingLayer ()

const TSLDataLayer *	getCoordinateProvidingLayer () const

bool	getDeclutterRange (const char featureName, double innerLimit, double outerLimit, const char dataLayerName=0, const char *detailLayerName=0)

bool	getDeviceCapabilities (int &horizontalSizeMM, int &verticalSizeMM, int &horizontalSizePixels, int &verticalSizePixels) const

bool	getDeviceCapabilities (TSLDeviceCapabilities &capabilities) const

void	getDUExtent (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2) const

bool	getFillStyleIndices (int *indices, int num)

bool	getFontStyleIndices (int *indices, int num)

bool	getLineStyleIndices (int *indices, int num)

void	getMUExtent (double x1, double y1, double x2, double y2) const

bool	getSymbolStyleIndices (int *indices, int num)

TSLDrawingSurfaceTiledBufferControl *	getTiledBufferController ()

void	getTMCExtent (TSLEnvelope &extent) const

void	getUUExtent (double x1, double y1, double x2, double y2) const

bool	getViewedLatLongRange (double latitude, double longitude, double *range, bool local=false, bool boundCheck=true) const

bool	latLongToDU (double latitude, double longitude, TSLDeviceUnits x, TSLDeviceUnits y, bool local=false) const

bool	latLongToMU (double latitude, double longitude, double x, double y, bool local=false) const

bool	latLongToTMC (double latitude, double longitude, TSLTMC x, TSLTMC y, bool local=false) const

bool	latLongToUU (double latitude, double longitude, double x, double y, bool local=false) const

bool	MUToDU (double x1, double y1, TSLDeviceUnits x2, TSLDeviceUnits y2) const

bool	MUToLatLong (double x, double y, double latitude, double longitude, bool local=false, bool boundCheck=true) const

bool	MUToTMC (double x1, double y1, TSLTMC x2, TSLTMC y2) const

bool	MUToUU (double x1, double y1, double x2, double y2) const

bool	pan (double x1, double y1, bool auto_redraw=true)

bool	pan (double x1, double y1, TSLDeviceUnits xDU, TSLDeviceUnits yDU, bool auto_redraw=true)

TSLMapQuery *	query (const char layerName, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int depth=-1, const char feature_name=NULL) const

TSLMapQuery *	query (const char layerName, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, TSLSelector selector) const

bool	redraw ()

bool	reset (bool auto_redraw=true)

bool	resize (double x1, double y1, double x2, double y2, bool auto_redraw=true, bool keep_aspect=false)

bool	rotate (double angle)

double	rotation () const

bool	setDeclutterRange (const char featureName, double innerLimit, double outerLimit, const char dataLayerName=0, const char *detailLayerName=0)

bool	setDeviceCapabilities (const int horizontalSizeMM=0, const int verticalSizeMM=0, const int horizontalSizePixels=0, const int verticalSizePixels=0)

bool	setDeviceCapabilities (const TSLDeviceCapabilities &capabilities)

void	setRedrawCallback (TSLDrawingSurfaceDrawCallback *callback)

bool	setupDynamicColours (const char *filename)

bool	setViewedLatLongRange (double latitude, double longitude, double range, bool local=false, bool auto_redraw=true, bool keep_aspect=false)

void	TMCperDU (double &xr, double &yr)

double	TMCperUU ()

bool	TMCToDU (TSLTMC x1, TSLTMC y1, TSLDeviceUnits x2, TSLDeviceUnits y2) const

bool	TMCToLatLong (TSLTMC x, TSLTMC y, double latitude, double longitude, bool local=false, bool boundCheck=true) const

bool	TMCToMU (TSLTMC x1, TSLTMC y1, double x2, double y2) const

bool	TMCToUU (TSLTMC x1, TSLTMC y1, double x2, double y2) const

bool	updateEntityExtent (TSLEntity entity, const char layerName)

void	userUnitOrigin (double x_origin, double y_origin)

void	userUnitOrigin (TSLUUEnum origin_enum)

void	userUnits (double factor)

double	userUnits ()

bool	UUToDU (double x1, double y1, TSLDeviceUnits x2, TSLDeviceUnits y2) const

bool	UUToLatLong (double x, double y, double latitude, double longitude, bool local=false, bool boundCheck=true) const

bool	UUToMU (double x1, double y1, double x2, double y2) const

bool	UUToTMC (double x1, double y1, TSLTMC x2, TSLTMC y2) const

bool	wndResize (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool auto_redraw=true, TSLResizeActionEnum action=TSLResizeActionNone)

bool	zoom (double percent, bool zoom_in, bool auto_redraw=true)

	TSLDrawingSurface ()

virtual	~TSLDrawingSurface ()

void	clearSymbolList ()

void	clearFontList ()

void	clearLineList ()

void	clearFillList ()

bool	removeFillStyle (TSLStyleID style)

bool	removeLineStyle (TSLStyleID style)

bool	removeSymbolStyle (TSLStyleID style)

bool	removeFontStyle (TSLStyleID style)

TSLStyleID	createFontID (const TSLSimpleString &name, TSLFontType meaningOfName, int fontWeight, bool italic=false, bool underline=false, bool antiAliased=false, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)

TSLStyleID	createStandardLineID (const unsigned char *pattern, TSLSize patternLength, int initialOffset, TSLLineScalingType scaleType)

TSLStyleID	createSymbolLineID (int symbolID, double size=0.0, TSLDimensionUnits sizeUnits=TSLDimensionUnitsUndefined, float rotation=0.0f, double anchorPointX=0.0, double anchorPointY=0.0, TSLDimensionUnits anchorPointUnits=TSLDimensionUnitsUndefined)

TSLStyleID	createStandardFillID (const unsigned char *pattern=NULL, TSLSize patternSizeInBytes=0, int patternXSize=0, int patternYSize=0)

TSLStyleID	createSymbolFillID (int symbolID, double size=0.0, TSLDimensionUnits sizeUnits=TSLDimensionUnitsUndefined, float rotation=0.0f, double anchorPointX=0.0, double anchorPointY=0.0, TSLDimensionUnits anchorPointUnits=TSLDimensionUnitsUndefined)

TSLStyleID	createSVGSymbolID (const TSLSimpleString &name, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)

TSLStyleID	createFontSymbolID (const TSLSimpleString &name, TSLFontType meaningOfName, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)

TSLStyleID	createRasterSymbolID (const TSLSimpleString &name, int xorigin, int yorigin, bool scaleable, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)

TSLStyleID	createSymbolIDFromSymbol (TSLStyleID symbolID, int numberofColourPairs, const int colourFrom, const int colourTo)

Public Member Functions inherited from TSLDrawingSurfaceBase
bool	addDataLayer (TSLDataLayer data_layer_interface, const char data_id)

bool	addDynamicRenderer (TSLDynamicRenderer renderer, TSLFeatureID featureID=-1, const char layerName=0)

bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)

void	attach (TSLDeviceContext handle)

void	attach (TSLWindowHandle handle)

void	attach (TSLDrawableHandle handle)

bool	bringInFrontof (const char move_data_layer, const char target_data_layer)

bool	bringToFront (const char *move_data_layer)

bool	clearAllDeclutterData (const char *layer_name=0)

void	clearAllDynamicRenderers ()

bool	clearBackgroundColour ()

bool	clearDeclutterData (const char feature_name, const char layer_name=0)

bool	clearDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)

bool	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)

bool	clearFrame ()

bool	copyDeclutterData (const char src_feature_name, const char dest_feature_name, const char src_layer_name=0, const char dest_layer_name=0)

void	detach ()

void	detachAllDynamicRenderers ()

bool	detachDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)

const char *	featureClass (TSLFeatureID feature_id)

bool	forceLayer (const char data_id, const char detail_layer_name)

bool	getBackgroundColour (TSLStyleID *value)

bool	getColourValue (int colour, unsigned char &r, unsigned char &g, unsigned char &b)

TSLDataLayer *	getDataLayer (const char *data_id)

bool	getDataLayerInfo (int N, TSLDataLayer dataLayer, const char layerName) const

bool	getDataLayerProps (const char data_id, TSLPropertyEnum property_id, TSLPropertyValue old_value)

bool	getDeclutterStatus (const char feature_name, TSLDeclutterStatusResultEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	getDeclutterStatus (TSLFeatureID feature_id, TSLDeclutterStatusResultEnum value, const char dataLayerName, const char *detailLayerName=0)

TSLDynamicRenderer *	getDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool result) const

bool	getFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributes result) const

int	getNumDataLayers () const

bool	getOption (TSLOptionEnum option)

void	id (int id_)

int	id () const

bool	idleProcess ()

bool	loadDeclutter (const char *filename)

bool	loadRendering (const char *filename)

TSLPickResultSet *	pick (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, TSLPickSelector *selector=0)

TSLPickResultSet *	pick (const char data_id, TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, TSLPickSelector selector=0)

bool	queryActiveLayer (const char data_id, char detail_layer_name, int detail_layer_name_size)

bool	removeDataLayer (const char *data_id)

bool	saveDeclutter (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)

bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)

bool	sendToBack (const char *move_data_layer)

bool	sendToBackOf (const char move_data_layer, const char target_data_layer)

bool	setBackgroundColour (int value)

bool	setCoordinateProvidingLayer (const char *layer_name)

bool	setDataLayerProps (const char *data_id, TSLPropertyEnum property_id, TSLPropertyValue new_value)

bool	setDeclutterStatus (const char feature_name, TSLDeclutterStatusEnum value, const char dataLayerName=0, const char *detailLayerName=0)

bool	setDeclutterStatus (TSLFeatureID feature_id, TSLDeclutterStatusEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	setDeclutterStatusOnAllFeatures (TSLDeclutterStatusEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int value)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double value)

bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool value)

bool	setFeatureRendering (const char featureName, TSLFeatureID featureID, TSLRenderingAttributes value)

bool	setFrame (int style, int colour, int thickness)

virtual void	setOption (TSLOptionEnum option, bool value)

double	TMCperMU ()

TSLDrawingSurfaceTypeEnum	type () const

void	userWord (void *ptr) const

void *	userWord () const

bool	cloneDynamicRenderersFrom (const TSLDrawingSurfaceBase *otherSurface)

void	addDuplicateLayers (bool value)

virtual	~TSLDrawingSurfaceBase ()

Static Public Member Functions
static void	cleanup ()

static bool	copy (TSLDrawingSurface copyTo, TSLDrawingSurface copyFrom, bool copyUserData=false)

static TSLStyleID	getIDOfNearestColour (int r, int g, int b)

static bool	loadStandardConfig (const char *path=0, bool delayLoadIncludes=false)

static bool	setupColours (const char *filename)

static bool	setupFillStyles (const char *filename, bool delayLoadIncludes=false)

static bool	setupFonts (const char *filename, bool delayLoadIncludes=false)

static bool	setupLineStyles (const char *filename, bool delayLoadIncludes=false)

static bool	setupSymbols (const char *filename, bool delayLoadIncludes=false)

static void	disableAntiAliasFonts ()

static void	enableAntiAliasFonts ()

Static Public Member Functions inherited from TSLDrawingSurfaceBase
static bool	addLoader (TSLFileLoader *loader)

static bool	addPathList (TSLPathList *path_list)

static bool	findFile (const char *filename, TSLSimpleString &foundPath)

static TSLFileLoader *	getLoader ()

Additional Inherited Members
Protected Member Functions inherited from TSLDrawingSurfaceBase
	TSLDrawingSurfaceBase ()

Protected Attributes inherited from TSLDrawingSurfaceBase
void *	m_classID

Constructor & Destructor Documentation

◆ TSLDrawingSurface()

TSLDrawingSurface::TSLDrawingSurface ( )

◆ ~TSLDrawingSurface()

virtual TSLDrawingSurface::~TSLDrawingSurface ( )

virtual

Member Function Documentation

◆ cleanup()

static void TSLDrawingSurface::cleanup ( )

static

Free configuration settings.

This method should be called once before exiting the application which instanciates any number of TSLDrawingSurfaces. It will perform a full memory clean on all objects statically created by the application when setting it up, including any memory allocated during the setupFonts/Colours/Fillstyles/Linestyles/Symbols calls.

Note: This method cleans up static data and should only be called on exit. Calling at any other time and subsequently using MapLink may cause a crash.

This method is designed to minimise the close down messages from Visual Studio which are in this case false positives.

◆ clearAllRendering()

bool TSLDrawingSurface::clearAllRendering ( )

◆ clearDynamicColours()

bool TSLDrawingSurface::clearDynamicColours ( )

Clears the dynamic colour list.

Returns true on success, false otherwise.

◆ clearFillList()

void TSLDrawingSurface::clearFillList ( )

Clear the dynamic fill list - Future Enhancement

◆ clearFontList()

void TSLDrawingSurface::clearFontList ( )

Clear the dynamic font list - Future Enhancement

◆ clearLineList()

void TSLDrawingSurface::clearLineList ( )

Clear the dynamic line list - Future Enhancement

◆ clearSymbolList()

void TSLDrawingSurface::clearSymbolList ( )

Future Enhancements Do Not Use. Clear the dynamic symbol list - Future Enhancement

◆ clone()

virtual TSLDrawingSurface * TSLDrawingSurface::clone ( bool copyUserData = false )

pure virtual

This method clones the drawing surface and creates another drawing surface which reference the same data layers, data layer properties, options and coordinate system configuration.

Parameters

copyUserData If true, the userID and userWord will be copied to the new surface.

Returns: new cloned drawing surface, NULL on error.

Implemented in TSLDXAcceleratedSurface, TSLMotifSurface, TSLNTSurface, TSLOpenGLSurface, TSLWGLAcceleratedSurface, and TSLX11GLAcceleratedSurface.

◆ copy()

static bool TSLDrawingSurface::copy	(	TSLDrawingSurface *	copyTo,
		TSLDrawingSurface *	copyFrom,
		bool	copyUserData = false )

static

Copies the contents of the drawing surface from 'copyFrom' to 'copyTo'.

The copy does not copy any HDC, HWND, Display* etc... settings.

The perceived purpose of this method is for printing surfaces which do not support printing.

The copy is not a deep copy as it takes references to the layers.

The copy does not copy any dynamic resources.

Parameters

copyTo	Drawing Surface to copy too.
copyFrom	Drawing Surface to copy from.
copyUserData	If true, the userID and userWord will be copied to the new surface.

Returns: true if successful, false otherwise.

◆ createFontID()

TSLStyleID TSLDrawingSurface::createFontID	(	const TSLSimpleString &	name,
		TSLFontType	meaningOfName,
		int	fontWeight,
		bool	italic = false,
		bool	underline = false,
		bool	antiAliased = false,
		const unsigned char *	memoryBlock = NULL,
		TSLSize	memoryBlockSize = 0 )

Create a Font-style - Future Enhancement

◆ createFontSymbolID()

TSLStyleID TSLDrawingSurface::createFontSymbolID	(	const TSLSimpleString &	name,
		TSLFontType	meaningOfName,
		const unsigned char *	memoryBlock = NULL,
		TSLSize	memoryBlockSize = 0 )

Create a Symbol-style - Future Enhancement

◆ createRasterBuffer()

TSLRasterBuffer * TSLDrawingSurface::createRasterBuffer	(	unsigned int	width,
		unsigned int	height,
		TSLRasterBuffer::Format	format,
		TSLRasterBuffer::FilterMode	filterMode = TSLRasterBuffer::Linear )

Creates a new object that can be used to draw rasters to a MapLink drawing surface through the TSLRenderingInterface. For details on how to use the returned object refer to the class documentation for TSLRasterBuffer.

Parameters

width	The width in pixels of the raster to create.
height	The height in pixels of the raster to create.
format	The image format to use for the raster.
filterMode	The filtering mode to use when drawing the raster at a different resolution to the underlying image data.

◆ createRasterSymbolID()

TSLStyleID TSLDrawingSurface::createRasterSymbolID	(	const TSLSimpleString &	name,
		int	xorigin,
		int	yorigin,
		bool	scaleable,
		const unsigned char *	memoryBlock = NULL,
		TSLSize	memoryBlockSize = 0 )

Create a Symbol-style - Future Enhancement

◆ createStandardFillID()

TSLStyleID TSLDrawingSurface::createStandardFillID	(	const unsigned char *	pattern = NULL,
		TSLSize	patternSizeInBytes = 0,
		int	patternXSize = 0,
		int	patternYSize = 0 )

Create a Fill-style - Future Enhancement

◆ createStandardLineID()

TSLStyleID TSLDrawingSurface::createStandardLineID	(	const unsigned char *	pattern,
		TSLSize	patternLength,
		int	initialOffset,
		TSLLineScalingType	scaleType )

Create a Line-style - Future Enhancement

◆ createSVGSymbolID()

TSLStyleID TSLDrawingSurface::createSVGSymbolID	(	const TSLSimpleString &	name,
		const unsigned char *	memoryBlock = NULL,
		TSLSize	memoryBlockSize = 0 )

Create a Symbol-style - Future Enhancement - not implemented

◆ createSymbolFillID()

TSLStyleID TSLDrawingSurface::createSymbolFillID	(	int	symbolID,
		double	size = 0.0,
		TSLDimensionUnits	sizeUnits = TSLDimensionUnitsUndefined,
		float	rotation = 0.0f,
		double	anchorPointX = 0.0,
		double	anchorPointY = 0.0,
		TSLDimensionUnits	anchorPointUnits = TSLDimensionUnitsUndefined )

Create a Fill-style - Future Enhancement - not implemented

◆ createSymbolIDFromSymbol()

TSLStyleID TSLDrawingSurface::createSymbolIDFromSymbol	(	TSLStyleID	symbolID,
		int	numberofColourPairs,
		const int *	colourFrom,
		const int *	colourTo )

Create a Symbol-style - Future Enhancement - not implemented

◆ createSymbolLineID()

TSLStyleID TSLDrawingSurface::createSymbolLineID	(	int	symbolID,
		double	size = 0.0,
		TSLDimensionUnits	sizeUnits = TSLDimensionUnitsUndefined,
		float	rotation = 0.0f,
		double	anchorPointX = 0.0,
		double	anchorPointY = 0.0,
		TSLDimensionUnits	anchorPointUnits = TSLDimensionUnitsUndefined )

Create a Line-style - Future Enhancement - not implemented

◆ declutterIsVisible()

bool TSLDrawingSurface::declutterIsVisible	(	const char *	feature_name,
		double	resolution = 0.0,
		const char *	layer_name = 0 ) const

Query for feature visibility at specified resolution on specified layer.

This method allows the user to query whether the feature defined by the input parameter feature_name, is visible at the resolution specified by the input parameter resolution.

Parameters

feature_name	Name of the feature being queried.
resolution	User units per device unit. 0.0 may be used to specify the current screen resolution.
layer_name	: The data layer to set the decluttering value for. If the name supplied does not match a loaded layer then this will fail, returning true.

Returns: This method true if the feature would be visible at the specified resolution or if no declutter information is found for this feature. Returns false if it is not visible.

◆ disableAntiAliasFonts()

static void TSLDrawingSurface::disableAntiAliasFonts ( )

static

Disable anti-aliasing of fonts on the GDI drawing surface

Calling this method will disable font anti-aliasing in all instances of the TSLNTSurface This change will persist until the application terminates, or calls enableAntiAliasFonts().

◆ drawDU()

bool TSLDrawingSurface::drawDU	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLDeviceUnits	x2,
		TSLDeviceUnits	y2,
		bool	clear,
		bool	updateExtentOnly = false )

Draw area of map onto drawing surface.

This method requests the TSLDrawingSurface to redraw the MapLink data within the area defined by the input co-ordinates. This method may be called whenever a part of the Drawing Surface has been exposed through some action.

Note, this method will only redraw the primitives if the view or decluttering have changed, or if any of the data layers have been notified as changed. If the drawing surface is double buffered, the attached TSLDataLayers are drawn into the double buffer and then the double buffer is written to the window handle. Any layer buffering is also taken into account.

If an individual TSLDatalayer is double buffered, and the user unit extent of the Drawing Surface has not changed, then the existing double buffer is copied to the attached window handle. If the user unit extent has changed, then the TSLDataLayer is drawn into the double buffer and then the double buffer is written to the window handle.

The updateExtentOnly flag is used to update only certain areas of the screen. Under some circumstances, such as a paint message from Windows, it is necessary to clip the area that is drawn to the window. However, if the window is partially obscured, then any double buffers will only be partially drawn and may thus contain invalid data. If you are certain that only the specified area needs updating then set this flag to true, otherwise set it to false.

Parameters

x1	x value of bottom left co-ordinate (in device units) of the area to redraw.
y1	y value of bottom left coordinate (in device units) of the area to redraw.
x2	x value of top right co-ordinate (in device units) of the area to redraw.
y2	y value of top right coordinate (in device units) of the area to redraw.
clear	If true this will clear the specified area before drawing any of the data.
updateExtentOnly	See drawUU.

Returns: true on success, false otherwise.

◆ drawUU()

bool TSLDrawingSurface::drawUU	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		bool	clear,
		bool	updateExtentOnly = false )

Draw area of map onto drawing surface.

This method requests the TSLDrawingSurface to redraw the MapLink data within the area defined by the input co-ordinates. This method may be called whenever a part of the Drawing Surface has been exposed through some action.

Note, this method will only redraw the primitives if the view or decluttering have changed, or if any of the data layers have been notified as changed. If the drawing surface is double buffered, the attached TSLDataLayers are drawn into the double buffer and then the double buffer is written to the window handle. Any layer buffering is also taken into account.

The updateExtentOnly flag is used to update only certain areas of the screen. Under some circumstances, such as a paint message from Windows, it is necessary to clip the area that is drawn to the window. However, if the window is partially obscured, then any double buffers will only be partially drawn and may thus contain invalid data. If you are certain that only the specified area needs updating then set this flag to true, otherwise set it to false.

Parameters

(x1,y1)	Bottom left co-ordinate (in user-units) of the area to redraw.
(x2,y2)	Top right co-ordinate (in user-units) of the area to redraw.
clear	If true this will clear the specified area before drawing any of the data.
updateExtentOnly	If true, then the updates to buffers and the window are clipped to the specified extent, otherwise only updates to the window are clipped.

Returns: true on success, false otherwise.

◆ DUToLatLong()

bool TSLDrawingSurface::DUToLatLong	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		double *	latitude,
		double *	longitude,
		bool	local = false,
		bool	boundCheck = true ) const

Convert from device co-ordinate to latitude/longitude co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x,y)	Device unit co-ordinate
(latitude,longitude)	Storage for lat/lon co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/lon returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: true on success, false otherwise.

◆ DUToMU()

bool TSLDrawingSurface::DUToMU	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		double *	x2,
		double *	y2 ) const

Convert device unit co-ordinate to map units.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Device unit co-ordinate
(x2,y2)	Storage for map unit co-ordinate.

Returns: true on success, false otherwise.

◆ DUToTMC()

bool TSLDrawingSurface::DUToTMC	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Convert device co-ordinate to internal co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Device co-ordinate.
(x2,y2)	Storage for internal co-ordinate.

Returns: true on success, false otherwise.

◆ DUToUU()

bool TSLDrawingSurface::DUToUU	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		double *	x2,
		double *	y2 ) const

Convert from device co-ordinate to user unit co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Device unit co-ordinate
(x2,y2)	Storage for user unit co-ordinate.

Returns: true on success, false otherwise.

◆ enableAntiAliasFonts()

static void TSLDrawingSurface::enableAntiAliasFonts ( )

static

Enable anti-aliasing of fonts on the GDI drawing surface

Calling this method will enable font anti-aliasing in all instances of the TSLNTSurface This change will persist until the application terminates, or calls disableAntiAliasFonts().

◆ findEntityDU()

TSLEntity * TSLDrawingSurface::findEntityDU	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture,
		int	depth,
		const char *	feature_name = NULL )

Find an entity at device unit position.

Note: For simple selection through a user interaction, see findSelectedEntityDU()

This method allows the user to retrieve an entity from any data layer attached to the drawing surface according to a location. The entity search can be refined by setting the last parameter in the argument list to a valid feature name. In this case an entity will be returned only if it belongs to the named feature. Only data layers which are visible and detectable will be searched. Only entities which are not decluttered on the drawing surface will be examined.

The TSLEntity returned is embedded within the tile so should not be destroyed by the user unless it is not required. Note that an entity deleted from a MapDataLayer tile may be reloaded when the tile is removed from the cache.

The search algorithm is as follows:

Iterate across visible, detectable data layers in reverse order (ie. from topmost to bottommost)
For map layers, the detail layer that would be used for drawing the aperture extent is used
In each layer, all entities whose last rendered extent overlaps the aperture extent are analysed further
- If a feature name is specified, only entities of that feature name are considered
- The analysis goes no deeper into the Entity Set hierarchy than specified below
- These entities have the distance to the selection point calculated
  - If the point is within a polygon, the distance to the polygon is 0.
  - If the point is within the last rendered extent of a text or symbol entity, the distance to that entity is 0
- If the distance is within the aperture distance then the entity is considered a candidate
- The results for a layer are sorted according to distance from the aperture and entity type
  - Entity types are sorted according to the following precedence and by distance within each type:
    - text
    - symbol
    - curves (arc/polylines)
    - surfaces (ellipse/rect/polygon)
    - entity sets
  - This means that text is always considered before symbols, etc.
- If any candidate entities are found in a layer, then the first visible entity in the sorted list is returned
- If no visible candidate entities are found in a layer, then the next layer is analysed

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

x,y	Co-ordinate of the location where to find the entity on the map. These co-ordinates are in device units.
aperture	This specifies an extent around the location co-ordinate in which to search for the entity. This is in device units.
depth	Specifies how deep to look before returning a pointer to an object. If the depth is 0 it searches at the highest level in the model (that is it will return a Group rather than an entity within the Group).
feature_name	If not NULL, only entities of this feature name will be checked.

Returns: a pointer to a TSLEntity if found, NULL otherwise.

◆ findEntityUU()

TSLEntity * TSLDrawingSurface::findEntityUU	(	double	x,
		double	y,
		double	aperture,
		int	depth,
		const char *	feature_name = NULL )

Find an entity at user unit position.

This method allows the user to retrieve an entity from any data layer attached to the drawing surface according to a location. The entity search can be refined by setting the last parameter in the argument list to a valid feature name. In this case an entity will be returned only if it belongs to the named feature. Only data layers which are visible and detectable will be searched. Only entities which are not decluttered on the drawing surface will be examined.

The TSLEntity returned is embedded within the tile so should not be destroyed by the user unless it is not required. Note that an entity deleted from a MapDataLayer tile may be reloaded when the tile is removed from the cache.

The search algorithm is as follows :

Iterate across visible, detectable data layers in reverse order (ie. from topmost to bottommost)
For map layers, the detail layer that would be used for drawing the aperture extent is used
In each layer, all entities whose last rendered extent overlaps the aperture extent are analysed further
- If a feature name is specified, only entities of that feature name are considered
- The analysis goes no deeper into the Entity Set hierarchy than specified below
- These entities have the distance to the selection point calculated
  - If the point is within a polygon, the distance to the polygon is 0.
  - If the point is within the last rendered extent of a text or symbol entity, the distance to that entity is 0
- If the distance is within the aperture distance then the entity is considered a candidate
- The results for a layer are sorted according to distance from the aperture and entity type
  - Entity types are sorted according to the following precedence and by distance within each type:
    - text
    - symbol
    - curves (arc/polylines)
    - surfaces (ellipse/rect/polygon)
    - entity sets
  - This means that text is always considered before symbols, etc.
- If any candidate entities are found in a layer, then the first visible entity in the sorted list is returned
- If no visible candidate entities are found in a layer, then the next layer is analysed

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

x,y	Co-ordinate of the location where to find the entity on the map. These co-ordinates are in user units.
aperture	This specifies an extent around the location co-ordinate in which to search for the entity. This is in user units.
depth	Specifies how deep to look before returning a pointer to an object. If the depth is 0 it searches at the highest level in the tile (that is it may return a Group rather than an entity within the Group).
feature_name	If not NULL, only entities of this feature name will be checked.

Returns: a pointer to a TSLEntity if found, NULL otherwise.

◆ findSelectedEntityDU()

TSLEntity * TSLDrawingSurface::findSelectedEntityDU	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture,
		int	depth = -1,
		bool	ignoreMapDataLayers = false )

Find an entity at device unit position.

This method allows the user to retrieve an entity from any data layer attached to the drawing surface according to a location. Only data layers which are visible and detectable will be searched. Only entities which are not decluttered on the drawing surface will be examined.

The TSLEntity returned may embedded within a map tile so should not be destroyed by the user unless it is not required. Note that an entity deleted from a MapDataLayer tile may be reloaded when the tile is removed from the cache.

The search algorithm is as follows:

Iterate across visible, detectable data layers in reverse order (i.e. from topmost to bottommost)
For map layers, the currently display detail layer is used
In each layer, all entities whose last rendered extent overlaps the aperture extent are analysed further
- The analysis goes no deeper into the Entity Set hierarchy than specified below
- These entities have the distance to the selection point calculated
- The entities are analysed in reverse display order (i.e. from topmost to bottommost)
  - If the point is within a polygon, the distance to the polygon is 0.
  - If the point is within the last rendered extent of a text or symbol entity, the distance to that entity is 0
  - Note that the extents may be bigger than they appear due to font sizing with text and hidden boundaries in symbols
- If the distance is within the aperture distance then the entity is considered a candidate
- If the calculated distance is 0 and the object is a surface (polygon/ellipse/rectangle), then the closest entity previously found is returned. If none have been found, then the surface is returned. This allows for selection of objects within a polygon.
- Apart from the special surface behaviour, the nearest visible candidate is the layer is returned
- If no visible candidate entities are found in a layer, then the next layer is analysed

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

x,y	Co-ordinate of the location where to find the entity on the map. These co-ordinates are in device units.
aperture	This specifies an extent around the location co-ordinate in which to search for the entity. This is in device units.
depth	Specifies how deep to look before returning a pointer to an object. If the depth is -1 (the default), then all entities are searched regardless of depth. If the depth is 0 it searches at the highest level in the model (that is it will return a Group rather than an entity within the Group).
ignoreMapDataLayers	If true, then map data layers are ignored, even if detectable

Returns: a pointer to a TSLEntity if found, NULL otherwise.

◆ findSelectedEntityUU()

TSLEntity * TSLDrawingSurface::findSelectedEntityUU	(	double	x,
		double	y,
		double	aperture,
		int	depth = -1,
		bool	ignoreMapDataLayers = false )

Find an entity at user unit position.

This method allows the user to retrieve an entity from any data layer attached to the drawing surface according to a location. Only data layers which are visible and detectable will be searched. Only entities which are not decluttered on the drawing surface will be examined.

The TSLEntity returned may embedded within a map tile so should not be destroyed by the user unless it is not required. Note that an entity deleted from a MapDataLayer tile may be reloaded when the tile is removed from the cache.

The search algorithm is as follows:

Iterate across visible, detectable data layers in reverse order (i.e. from topmost to bottommost)
For map layers, the currently display detail layer is used
In each layer, all entities whose last rendered extent overlaps the aperture extent are analysed further
- The analysis goes no deeper into the Entity Set hierarchy than specified below
- These entities have the distance to the selection point calculated
- The entities are analysed in reverse display order (i.e. from topmost to bottommost)
  - If the point is within a polygon, the distance to the polygon is 0.
  - If the point is within the last rendered extent of a text or symbol entity, the distance to that entity is 0
  - Note that the extents may be bigger than they appear due to font sizing with text and hidden boundaries in symbols
- If the distance is within the aperture distance then the entity is considered a candidate
- If the calculated distance is 0 and the object is a surface (polygon/ellipse/rectangle), then the closest entity previously found is returned. If none have been found, then the surface is returned. This allows for selection of objects within a polygon.
- Apart from the special surface behaviour, the nearest visible candidate is the layer is returned
- If no visible candidate entities are found in a layer, then the next layer is analysed

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

x,y	Co-ordinate of the location where to find the entity on the map. These co-ordinates are in user units.
aperture	This specifies an extent around the location co-ordinate in which to search for the entity. This is in user units.
depth	Specifies how deep to look before returning a pointer to an object. If the depth is -1 (the default), then all entities are searched regardless of depth. If the depth is 0 it searches at the highest level in the model (that is it will return a Group rather than an entity within the Group).
ignoreMapDataLayers	If true, then map data layers are ignored, even if detectable

Returns: a pointer to a TSLEntity if found, NULL otherwise.

◆ getColourIndices()

bool TSLDrawingSurface::getColourIndices	(	int **	indices,
		int *	num )

Query colour indices.

Queries colour indices specified in the colour file last loaded using setupColours. These indices may be be converted to OS specific handles using the colourValue method. Note that the indices are not necessarily contiguous.

Parameters

indices	Storage for pointer to indices. Populated if successful. The buffer is owned by the TSLDrawingSurface and should not be deleted.
num	Storage for number of indices in array.

Returns: true if the arguments were populated, false otherwise.

◆ getCoordinateProvidingLayer() [1/2]

TSLDataLayer * TSLDrawingSurface::getCoordinateProvidingLayer ( )

Returns the data layer that defines the coordinate system for the drawing surface. The coordinate system of this layer is used when performing coordinate conversions through the drawing surface (e.g. latLongToMU, MUToTMC).

The coordinate providing layer is normally the first data layer added to the drawing surface that has a TSLCoordinateSystem.

If no coordinate providing layer has been added to the drawing surface, this method returns NULL.

◆ getCoordinateProvidingLayer() [2/2]

const TSLDataLayer * TSLDrawingSurface::getCoordinateProvidingLayer ( ) const

Returns the data layer that defines the coordinate system for the drawing surface. The coordinate system of this layer is used when performing coordinate conversions through the drawing surface (e.g. latLongToMU, MUToTMC).

The coordinate providing layer is normally the first data layer added to the drawing surface that has a TSLCoordinateSystem.

If no coordinate providing layer has been added to the drawing surface, this method returns NULL.

◆ getDeclutterRange()

bool TSLDrawingSurface::getDeclutterRange	(	const char *	featureName,
		double *	innerLimit,
		double *	outerLimit,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Query automatic decluttering range.

This method retrieves the current visibility range for the named feature. This resolution range determines when a feature is visible. The resolution limits returned are valid only if the visibility status of this feature is set to automatic.

Parameters

featureName	Name of the feature.
innerLimit	Minimum resolution at which the feature type is visible (user units per device unit), i.e. maximum zoom in.
outerLimit	Maximum resolution at which the feature type is visible (user units per device unit), i.e. maximum zoom out.
dataLayerName	The name of the data layer to query. Defaults to 0 i.e. get for all layers.
detailLayerName	the name of the detail layer to query. Defaults to 0 to query all detail layers.

Returns: true on success, false otherwise.

◆ getDeviceCapabilities() [1/2]

bool TSLDrawingSurface::getDeviceCapabilities	(	int &	horizontalSizeMM,
		int &	verticalSizeMM,
		int &	horizontalSizePixels,
		int &	verticalSizePixels ) const

Returns the device capabilities as determined by the drawing surface, or as passed to setDeviceCapabilities. For more information on the meaning of these values refer to the documentation for setDeviceCapabilities.

Parameters

horizontalSizeMM	horizontal size of the visible screen in mm.
verticalSizeMM	vertical size of the visible screen in mm.
horizontalSizePixels	horizontal size of the screen in pixels.
verticalSizePixels	vertical size of the screen in pixels.

Returns: true if the values were populated, or false if the drawing surface is currently not attached to a device.

◆ getDeviceCapabilities() [2/2]

bool TSLDrawingSurface::getDeviceCapabilities ( TSLDeviceCapabilities & capabilities ) const

Returns the device capabilities as determined by the drawing surface, or as passed to setDeviceCapabilities. For more information on the meaning of these values refer to the documentation for setDeviceCapabilities.

Parameters

capabilities Will be populated with the current device capabilities

Returns: true if the values were populated, or false if the drawing surface is currently not attached to a device.

◆ getDUExtent()

void TSLDrawingSurface::getDUExtent	(	TSLDeviceUnits *	x1,
		TSLDeviceUnits *	y1,
		TSLDeviceUnits *	x2,
		TSLDeviceUnits *	y2 ) const

Query extent of window.

This method allows the user to query the extent of the window handle currently displayed in terms of device units. This is the same extent that will have been passed in the last call to 'wndResize'.

Parameters

(x1,y1)	Storage for top left co-ordinate of the extent in device units.
(x2,y2)	Storage for bottom right co-ordinate of the extent in device units.

◆ getFillStyleIndices()

bool TSLDrawingSurface::getFillStyleIndices	(	int **	indices,
		int *	num )

Query fill style indices.

Queries fill style indices specified in the fill style file last loaded using setupFillStyles. These indices may be be converted to OS specific handles using the fillStyleValue method. Note that the indices are not necessarily contiguous.

Parameters

indices	Storage for pointer to indices. Populated if successful. The buffer is owned by the TSLDrawingSurface and should not be deleted.
num	Storage for number of indices in array.

Returns: true if the arguments were populated, false otherwise.

◆ getFontStyleIndices()

bool TSLDrawingSurface::getFontStyleIndices	(	int **	indices,
		int *	num )

Query font style indices.

Queries font style indices specified in the font style file last loaded using setupFontStyles. These indices may be be converted to OS specific handles using the fontStyleValue method. Note that the indices are not necessarily contiguous.

Parameters

indices	Storage for pointer to indices. Populated if successful. The buffer is owned by the TSLDrawingSurface and should not be deleted.
num	Storage for number of indices in array.

Returns: true if the arguments were populated, false otherwise.

◆ getIDOfNearestColour()

static TSLStyleID TSLDrawingSurface::getIDOfNearestColour	(	int	r,
		int	g,
		int	b )

static

Find the closest supported colour.

Finds the closest supported colour to the RGB value passed in.

Parameters

r	red value (0-255)
g	green value (0-255)
b	blue value (0-255)

Returns: index of nearest colour, -1 on error.

◆ getLineStyleIndices()

bool TSLDrawingSurface::getLineStyleIndices	(	int **	indices,
		int *	num )

Query line style indices.

Queries line style indices specified in the line style file last loaded using setupLineStyles. These indices may be be converted to OS specific handles using the lineStyleValue method. Note that the indices are not necessarily contiguous.

Parameters

indices	Storage for pointer to indices. Populated if successful. The buffer is owned by the TSLDrawingSurface and should not be deleted.
num	Storage for number of indices in array.

Returns: true if the arguments were populated, false otherwise.

◆ getMUExtent()

void TSLDrawingSurface::getMUExtent	(	double *	x1,
		double *	y1,
		double *	x2,
		double *	y2 ) const

Query extent of data on TSLDrawingSurface.

This method allows the user to query the extent of the MapLink map data currently displayed in terms of map units.

Note: If the user application maintains such extent, this method should be called to refresh them after any operation applied on the TSLDrawingSurface which will affect the area of Maplink map data displayed.

Parameters

(x1,y1)	Storage for bottom left co-ordinate of the extent in map units.
(x2,y2)	Storage for top right co-ordinate of the extent in map units.

◆ getSymbolStyleIndices()

bool TSLDrawingSurface::getSymbolStyleIndices	(	int **	indices,
		int *	num )

Query symbol style indices.

Queries symbol style indices specified in the symbol style file last loaded using setupSymbols. These indices may be be converted to OS specific handles using the symbolStyleValue method. Note that the indices are not necessarily contiguous.

Parameters

indices	Storage for pointer to indices. Populated if successful. The buffer is owned by the TSLDrawingSurface and should not be deleted.
num	Storage for number of indices in array.

Returns: true if the arguments were populated, false otherwise.

◆ getTiledBufferController()

TSLDrawingSurfaceTiledBufferControl * TSLDrawingSurface::getTiledBufferController ( )

Returns an object that an application can use to change settings for tiled buffered layers. Tiled buffered layers must first be enabled using the TSLOptionTileBufferedLayers drawing surface option.

See the class documentation for TSLDrawingSurfaceTiledBufferControl for more details.

◆ getTMCExtent()

void TSLDrawingSurface::getTMCExtent ( TSLEnvelope & extent ) const

Query extent of data on TSLDrawingSurface.

This method allows the user to query the extent of the MapLink map data currently displayed in terms of TMC units.

Note: If the user application maintains such extent, this method should be called to refresh them after any operation applied on the TSLDrawingSurface which will affect the area of Maplink map data displayed.

Parameters

extent Storage for the extent.

◆ getUUExtent()

void TSLDrawingSurface::getUUExtent	(	double *	x1,
		double *	y1,
		double *	x2,
		double *	y2 ) const

Query extent of data on TSLDrawingSurface.

This method allows the user to query the extent of the MapLink map data currently displayed in terms of user units, ignoring any rotation that has been applied to the drawing surface.

Note: If the user application maintains such extent, this method should be called to refresh them after any operation applied on the TSLDrawingSurface which will affect the area of Maplink map data displayed.

Parameters

(x1,y1)	Storage for bottom left co-ordinate of the extent in user units.
(x2,y2)	Storage for top right co-ordinate of the extent in user units.

◆ getViewedLatLongRange()

bool TSLDrawingSurface::getViewedLatLongRange	(	double *	latitude,
		double *	longitude,
		double *	range,
		bool	local = false,
		bool	boundCheck = true ) const

Queries the extent of data currently in view. Returns the centre of the area in latitude and longitude in degrees, and the minimum range visible horizontally or vertically in map units. NOTE: This function is not appropriate for use when Dynamic Arc Support is enabled, since the X/Y aspect adjustment results in non-square TMC per DU values.

Parameters

latitude	returns the latitude of the centre of the currently viewed area, in degrees
longitude	returns the longitude of the centre of the currently viewed area, in degrees
range	returns the minimum visible distance horizontally or vertically, in map units
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/lon returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: true on success, false otherwise.

◆ latLongToDU()

bool TSLDrawingSurface::latLongToDU	(	double	latitude,
		double	longitude,
		TSLDeviceUnits *	x,
		TSLDeviceUnits *	y,
		bool	local = false ) const

Convert from latitude/longitude to device unit co-ordinate.

This operation will use the current Coordinate System to perform the conversion. This will usually be defined only for TSLMapDataLayers.

Parameters

(latitude,longitude)	Point to convert.
(x,y)	Storage for device unit co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.

Returns: true on success, false otherwise.

◆ latLongToMU()

bool TSLDrawingSurface::latLongToMU	(	double	latitude,
		double	longitude,
		double *	x,
		double *	y,
		bool	local = false ) const

Convert from latitude/longitude to Map Unit co-ordinate.

This operation will use the current Coordinate System to perform the conversion. This will usually be defined only for TSLMapDataLayers.

Parameters

(latitude,longitude)	Point to convert.
(x,y)	Storage for Map Unit co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.

Returns: true on success, false otherwise.

◆ latLongToTMC()

bool TSLDrawingSurface::latLongToTMC	(	double	latitude,
		double	longitude,
		TSLTMC *	x,
		TSLTMC *	y,
		bool	local = false ) const

Convert from latitude/longitude to internal TMC co-ordinate.

This operation will use the current Coordinate System to perform the conversion. This will usually be defined only for TSLMapDataLayers.

Parameters

(latitude,longitude)	Point to convert.
(x,y)	Storage for internal TMC co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.

Returns: true on success, false otherwise.

◆ latLongToUU()

bool TSLDrawingSurface::latLongToUU	(	double	latitude,
		double	longitude,
		double *	x,
		double *	y,
		bool	local = false ) const

Convert from latitude/longitude to User Unit co-ordinate.

This operation will use the current Coordinate System to perform the conversion. This will usually be defined only for TSLMapDataLayers.

Parameters

(latitude,longitude)	Point to convert.
(x,y)	Storage for User Unit co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.

Returns: true on success, false otherwise.

◆ loadStandardConfig()

static bool TSLDrawingSurface::loadStandardConfig	(	const char *	path = 0,
		bool	delayLoadIncludes = false )

static

Loads the tsl*.dat files with the default names into all drawing surfaces. This is equivalent to firstly adding a pathlist configured to find data files, fonts, symbols and so on in the default subdirectories (e.g. addKeyedDirectory(root+"fonts", 0, ".thf", TSLCompressedDefault) ),

and secondly calling:

setupColours( "tslcolours.dat" );
setupFonts( "tslfonts.dat" );
setupSymbols( "tslsymbols.dat" );
setupLineStyles( "tsllinestyles.dat" );
setupFillStyles( "tslfillstyles.dat" );

Parameters

path If supplied, this is the path from which the configuration files are to be loaded. If null, then the files are assumed to be present in the config subdirectory of the maplink installation on the local machine (whose location is found using TSLUtilityFunctions::getMapLinkHome()). Note that using a relative path here will cause problems if the working directory changes as the path will no longer point to the correct directory, so it is recommended to use an absolute path.

delayLoadIncludes If this flag is set to true the all referenced include files in each of the configuration lists will only be loaded when they are required rather than during this call. This should not be set to true if rendering or querying any fillstyles, fonts, linestyles or symbols in a multithreaded environment.

Returns: true if successful, false otherwise.

◆ MUToDU()

bool TSLDrawingSurface::MUToDU	(	double	x1,
		double	y1,
		TSLDeviceUnits *	x2,
		TSLDeviceUnits *	y2 ) const

Convert map unit co-ordinate to device units.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Map unit co-ordinate
(x2,y2)	Storage for device unit co-ordinate.

Returns: true on success, false otherwise.

◆ MUToLatLong()

bool TSLDrawingSurface::MUToLatLong	(	double	x,
		double	y,
		double *	latitude,
		double *	longitude,
		bool	local = false,
		bool	boundCheck = true ) const

Convert map unit co-ordinate to latitude/longitudes.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x,y)	Map unit co-ordinate
(latitude,longitude)	Storage for lat/lon co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/lon returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: true on success, false otherwise.

◆ MUToTMC()

bool TSLDrawingSurface::MUToTMC	(	double	x1,
		double	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Convert map unit co-ordinate to internal units.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Map unit co-ordinate
(x2,y2)	Storage for internal TMC unit co-ordinate.

Returns: true on success, false otherwise.

◆ MUToUU()

bool TSLDrawingSurface::MUToUU	(	double	x1,
		double	y1,
		double *	x2,
		double *	y2 ) const

Convert map unit co-ordinate to user units.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Map unit co-ordinate
(x2,y2)	Storage for user unit co-ordinate.

Returns: true on success, false otherwise.

◆ pan() [1/2]

bool TSLDrawingSurface::pan	(	double	x1,
		double	y1,
		bool	auto_redraw = true )

Make specified point centre of display.

This method will cause the TSLDrawingSurface to pan so that the input co-ordinates are at the centre of the display area. If 'auto_redraw' it true, then the TSLDrawingSurface will automatically draw the new requested area on the window handle to which the TSLDrawingSurface is attached.

Note: The pan may cause the extent of the MapLink map data to overflow the extent of TMC coordinate space. In this case, the pan operation is not applied and the function returns false.

Parameters

(x1,y1)	Point co-ordinates (in user units) to be set at the centre of the display.
auto_redraw	If true, the TSLDrawingSurface redraws automatically.

Returns: true on success, false otherwise.

◆ pan() [2/2]

bool TSLDrawingSurface::pan	(	double	x1,
		double	y1,
		TSLDeviceUnits	xDU,
		TSLDeviceUnits	yDU,
		bool	auto_redraw = true )

Make specified point in UU space, move to specified point in DU space.

This method is typically used for grab-style panning. It is necessary since any Dynamic Arc adjustments may affect the device unit positioning of a normal pan.

This method will cause the TSLDrawingSurface to pan so that the input coordinates are at the specified point in the display area. If 'auto_redraw' is true, then the TSLDrawingSurface will automatically draw the new requested area on the window handle to which the TSLDrawingSurface is attached.

Note: The pan may cause the extent of the MapLink map data to overflow the extent of TMC coordinate space. In this case, the pan operation is not applied and the function returns false.

Parameters

(x1,y1)	Point coordinates (in user units) to be set at the specified point in the display area.
(xDU,yDU)	Point coordinates (in device units) for (x1,y1) to move to.
auto_redraw	If true, the TSLDrawingSurface redraws automatically.

Returns: true on success, false otherwise.

◆ query() [1/2]

TSLMapQuery * TSLDrawingSurface::query	(	const char *	layerName,
		TSLTMC	x1,
		TSLTMC	y1,
		TSLTMC	x2,
		TSLTMC	y2,
		int	depth = -1,
		const char *	feature_name = NULL ) const

Query for entities in extent.

The detail layer used is the layer for the current drawing surface extent.

This method requests the named layer to return a TSLMapQuery object which allows the user to access the data tiles required for the display of the specified area. The TSLMapQuery for a TSLDrawingSurface is only valid for immediate use since the data tiles to which they refer may be removed from memory if the cache is flushed.

In the default case, all tiles whose extent intersects the specified extent will be returned. These will include all entities within those tiles, even though some individual entities may not be within the extent.

Alternatively, if a depth is specified, then the query recurses into the tiles and returns only those individual entities that whose extents intersect the region. An optional feature name may also be specified.

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

layerName	The name of the layer to query
(x1,y1)	The bottom left co-ordinate of the specified area (in internal TMC units)
(x2,y2)	the top right co-ordinate of the specified area (in internal TMC units)
depth	Specifies how deep to look before returning a pointer to an object. If the depth is -1 (the default), individual entities are returned. If the depth is 0 it searches at the highest level in the tile (that is it may return a Group rather than an entity within the Group).
feature_name	If not NULL, only entities of this feature name will be checked.

Returns: a pointer to a TSLMapQuery object. If NULL, it indicates that no tiles were found for the specified area.

◆ query() [2/2]

TSLMapQuery * TSLDrawingSurface::query	(	const char *	layerName,
		TSLTMC	x1,
		TSLTMC	y1,
		TSLTMC	x2,
		TSLTMC	y2,
		TSLSelector *	selector ) const

Query for entities in extent based on a client-supplied search criteria.

The detail layer used is the layer for the current drawing surface extent.

This method requests the named layer to return a TSLMapQuery object which allows the user to access the data tiles required for the display of the specified area, or entities within those tiles. The TSLMapQuery for a TSLDrawingSurface is only valid for immediate use since the data tiles to which they refer may be removed from memory if the cache is flushed.

The client must specify the selection policy through a suitable TSLSelector-derived object.

NOTE: When querying an Optimised map the query may return objects that can not be further analysed.

Parameters

layerName	The name of the layer to query
(x1,y1)	The bottom left co-ordinate of the specified area (in internal TMC units)
(x2,y2)	the top right co-ordinate of the specified area (in internal TMC units)
selector	Specifies the selection criteria. See TSLSelector and TSLSelectorActionType for further details.

◆ redraw()

bool TSLDrawingSurface::redraw ( )

Clears and redraws the entire visible extent of the surface (as specified to wndResize).

◆ removeFillStyle()

bool TSLDrawingSurface::removeFillStyle ( TSLStyleID style )

Remove a style from a Dynamic List - Future Enhancement

◆ removeFontStyle()

bool TSLDrawingSurface::removeFontStyle ( TSLStyleID style )

Remove a style from a Dynamic List - Future Enhancement

◆ removeLineStyle()

bool TSLDrawingSurface::removeLineStyle ( TSLStyleID style )

Remove a style from a Dynamic List - Future Enhancement

◆ removeSymbolStyle()

bool TSLDrawingSurface::removeSymbolStyle ( TSLStyleID style )

Remove a style from a Dynamic List - Future Enhancement

◆ reset()

bool TSLDrawingSurface::reset ( bool auto_redraw = true )

Reset to full view.

This method resets the current UU extent so that the maximum extent of the attached TSLDataLayers is displayed in the attached window extent.

Parameters

auto_redraw If true, automatically redraws the window.

Returns: true if successful, false otherwise.

◆ resize()

bool TSLDrawingSurface::resize	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		bool	auto_redraw = true,
		bool	keep_aspect = false )

Changes displayed extent of map.

This method informs the TSLDrawingSurface of the map area that it is to be displayed. When the TSLDrawingSurface is first attached to the handle, it must be given the co-ordinates of the data area that it is to display.

Note: The resize may cause the extent of the MapLink map data to overflow the extent of TMC coordinate space. In this case, the resize operation is not applied and the function return false.

Parameters

(x1,y1)	Bottom left co-ordinate (in user-units) of the area to redraw.
(x2,y2)	Top right co-ordinate (in user-units) of the area to redraw.
auto_redraw	If true, will result in the whole drawing surface area being redrawn. Defaults to true.
keep_aspect	If true, will attempt to maintain the aspect ratio according to the current window aspect ratio. Defaults to false.

Returns: true on success, false otherwise.

◆ rotate()

bool TSLDrawingSurface::rotate ( double angle )

Rotate the vector map display.

This method rotates the display of the MapLink map data. It does not affect the data in any way, only the display of the data. The data will rotate around the current extent centre.

Note: The rotation may cause the extent of the MapLink map data to overflow the internal TMC co-ordinate limits, in which case the rotation is not applied and the method returns false.

Note: If you need to rotate raster data, please consider using the TSLOpenGLSurface, or the Accelerator SDK. Samples exist for both of these approaches.

Parameters

angle Angle of the rotation (in radians), +ve anti-clockwise from the +ve X axis.

Returns: true if the display has been rotated successfully, false otherwise.

◆ rotation()

double TSLDrawingSurface::rotation ( ) const

Queries the current rotation of the vector map display.

This method queries the current rotation the display of the MapLink map data.

Returns angle of the rotation (in radians), +ve anti-clockwise from the +ve X axis.

◆ setDeclutterRange()

bool TSLDrawingSurface::setDeclutterRange	(	const char *	featureName,
		double	innerLimit,
		double	outerLimit,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Set automatic decluttering range.

This method sets the resolution range for which the named feature type is visible. This is only applicable when the visibility mode is TSLDeclutterStatusAuto. The range values are given as the number of user units per device unit.

The declutter status is set to TSLDeclutterStatusAuto after this method is called.

Parameters

featureName	Name of the feature type to set the visibility range for.
innerLimit	Minimum resolution at which the feature type is visible (user units per device unit), i.e. maximum zoom in.
outerLimit	Maximum resolution at which the feature type is visible (user units per device unit), i.e. maximum zoom out.
dataLayerName	The data layer to set the decluttering value for. Default is 0 i.e. set for all layers.
detailLayerName	the detail layer to set the cluttering value for. Default is 0 to set for all detail layers.

Returns: true on success, false otherwise.

◆ setDeviceCapabilities() [1/2]

bool TSLDrawingSurface::setDeviceCapabilities	(	const int	horizontalSizeMM = 0,
		const int	verticalSizeMM = 0,
		const int	horizontalSizePixels = 0,
		const int	verticalSizePixels = 0 )

Set the device capabilities.

The set values are used when drawing items whose dimensions are defined as TSLDimensionUnitsPoints.

This method only needs to be called it the values need to be adjusted or reset to the default.

The set values will be discarded if attach is called.

The settings will not be used when a call is made to drawToHDC or drawToDrawable. The user will need to pass in the device capabilities to these methods (defaults for the device will be used otherwise).

Default values are obtained from the underlying drawing system.

On Windows the values can be obtained using the Windows SDK method: GetDeviceCaps.

On X11 targets the values can be obtained using the macros found in Xlib.h: DisplayWidthMM, DIsplayHeightMM, DisplayWidth, DisplayHeight.

If the parameters are all set to zero the method queries the System defaults and sets those values.

Parameters

horizontalSizeMM	horizontal size of the visible screen in mm's.
verticalSizeMM	vertical size of the visible screen in mm's.
horizontalSizePixels	horizontal size of the screen in pixels.
verticalSizePixels	vertical size of the screen in pixels.

Returns: true on success, false otherwise.

◆ setDeviceCapabilities() [2/2]

bool TSLDrawingSurface::setDeviceCapabilities ( const TSLDeviceCapabilities & capabilities )

Set the device capabilities.

The set values are used when drawing items whose dimensions are defined as TSLDimensionUnitsPoints.

This method only needs to be called it the values need to be adjusted or reset to the default.

The set values will be discarded if attach is called.

The settings will not be used when a call is made to drawToHDC or drawToDrawable. The user will need to pass in the device capabilities to these methods (defaults for the device will be used otherwise).

Default values are obtained from the underlying drawing system.

On Windows the values can be obtained using the Windows SDK method: GetDeviceCaps.

On X11 targets the values can be obtained using the macros found in Xlib.h: DisplayWidthMM, DIsplayHeightMM, DisplayWidth, DisplayHeight.

If the parameters are all set to zero the method queries the System defaults and sets those values.

Parameters

capabilities The capabilities of the device.

Returns: true on success, false otherwise.

◆ setRedrawCallback()

void TSLDrawingSurface::setRedrawCallback ( TSLDrawingSurfaceDrawCallback * callback )

Sets the callback object to use when the drawing surface needs to trigger a redraw. This is currently used by tiled buffered layers.

The user retains ownership of the callback object.

Parameters

callback The callback object to use. Passing NULL clears any existing callback.

◆ setupColours()

static bool TSLDrawingSurface::setupColours ( const char * filename )

static

Load colour definition file.

This method allows the user to set up a list of colours that will be used by all TSLDrawingSurfaces.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Parameters

filename Name of the colour file.

Returns: true on success, false otherwise.

◆ setupDynamicColours()

bool TSLDrawingSurface::setupDynamicColours ( const char * filename )

Load colour definition file into the surface dynamic colour list.

This method allows the user to set up a list of colours which are used only by this instance of the Drawing Surface.

The current dynamic colours are not cleared. The colours loaded will overwrite any colour index that already exist.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Parameters

filename Name of the colour file.

Returns: true on success, false otherwise.

◆ setupFillStyles()

static bool TSLDrawingSurface::setupFillStyles	(	const char *	filename,
		bool	delayLoadIncludes = false )

static

Load fill style definition file.

This method allows the user to set up the list of fill styles that will be used by all TSLDrawingSurfaces.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Note: This method should only be called once during an application's initialisation phase. Calling this method after the application has started rendering is not recommended.

Parameters

filename	Name of the fill style file.
delayLoadIncludes	If this flag is set to true the all referenced include files in the fillstyle list will only be loaded when they are required rather than during this call. This should not be set to true if rendering or querying fillstyles in a multithreaded environment.

Returns: true on success, false otherwise.

◆ setupFonts()

static bool TSLDrawingSurface::setupFonts	(	const char *	filename,
		bool	delayLoadIncludes = false )

static

Load font definition file.

This method allows the user to set up the list of fonts that will be used by all TSLDrawingSurface when rendering text.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Note: This method should only be called once during an application's initialisation phase. Calling this method after the application has started rendering is not recommended.

Parameters

filename	Name of the font file.
delayLoadIncludes	If this flag is set to true the all referenced include files in the font list will only be loaded when they are required rather than during this call. This should not be set to true if rendering or querying fonts in a multithreaded environment.

Returns: true on success, false otherwise.

◆ setupLineStyles()

static bool TSLDrawingSurface::setupLineStyles	(	const char *	filename,
		bool	delayLoadIncludes = false )

static

Load line style definition file.

This method allows the user to set up the list of line styles that will be used by all TSLDrawingSurfaces.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Note: This method should only be called once during an application's initialisation phase. Calling this method after the application has started rendering is not recommended.

Parameters

filename	Name of the line style file.
delayLoadIncludes	If this flag is set to true the all referenced include files in the linestyle list will only be loaded when they are required rather than during this call. This should not be set to true if rendering or querying linestyles in a multithreaded environment.

Returns: true on success, false otherwise.

◆ setupSymbols()

static bool TSLDrawingSurface::setupSymbols	(	const char *	filename,
		bool	delayLoadIncludes = false )

static

Load symbol definition file.

This method allows the user to set up the list of symbols that will be used by all TSLDrawingSurfaces.

If addPathList or loadStandardConfig has been called then the pathlist is used to search for the file in suitable directories (using keying), if not then the system Path and the environment variable MAPLINK_PATH are used to search for the file, or alternatively the filename may be fully qualified.

Note: This method should only be called once during an application's initialisation phase. Calling this method after the application has started rendering is not recommended.

Parameters

filename	Name of the symbol file.
delayLoadIncludes	If this flag is set to true the all referenced include files in the symbol list will only be loaded when they are required rather than during this call. This should not be set to true if rendering or querying symbols in a multithreaded environment.

Returns: true on success, false otherwise.

◆ setViewedLatLongRange()

bool TSLDrawingSurface::setViewedLatLongRange	(	double	latitude,
		double	longitude,
		double	range,
		bool	local = false,
		bool	auto_redraw = true,
		bool	keep_aspect = false )

Sets the extent of data to view. Takes the centre of the area in latitude and longitude in degrees, and the minimum range to make visible horizontally or vertically in map units. NOTE: This function is not appropriate for use when Dynamic Arc Support is enabled, since the X/Y aspect adjustment results in non-square TMC per DU values.

Parameters

latitude	the latitude to place at the centre of the viewed area, in degrees
longitude	the longitude to place at the centre of the viewed area, in degrees
range	the minimum distance to make visible horizontally or vertically, in map units
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
auto_redraw	If true, will result in the whole drawing surface area being redrawn.
keep_aspect	If true, will attempt to maintain the aspect ratio according to the current window aspect ratio. If false, the aspect ratio will be changed to meet the given range in both directions.

Returns: true on success, false otherwise.

◆ TMCperDU()

void TSLDrawingSurface::TMCperDU	(	double &	xr,
		double &	yr )

Query current screen resolution, varying in X and Y axis. These are usually the same, but may differ - e.g. Dynamic Arc projections.

This method gives the current resolution of the screen. This value is in internal TMC co-ordinates per device unit (pixel).

Parameters

xr	Storage for X axis resolution
yr	Storage for Y axis resolution

◆ TMCperUU()

double TSLDrawingSurface::TMCperUU ( )

Query number of TMC units per user unit.

This value is the number of internal TMC co-ordinates per user unit. These is based upon the last map data layer added to the drawing surface.

Returns the TMC units per user unit, 0.0 on error.

◆ TMCToDU()

bool TSLDrawingSurface::TMCToDU	(	TSLTMC	x1,
		TSLTMC	y1,
		TSLDeviceUnits *	x2,
		TSLDeviceUnits *	y2 ) const

Converts internal co-ordinate to device co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Internal co-ordinate
(x2,y2)	Storage for device co-ordinate .

Returns: true on success, false otherwise.

◆ TMCToLatLong()

bool TSLDrawingSurface::TMCToLatLong	(	TSLTMC	x,
		TSLTMC	y,
		double *	latitude,
		double *	longitude,
		bool	local = false,
		bool	boundCheck = true ) const

Convert from internal TMC co-ordinate to latitude/longitude.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x,y)	Internal TMC co-ordinate.
(latitude,longitude)	Storage for lat/lon co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/lon returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: true on success, false otherwise.

◆ TMCToMU()

bool TSLDrawingSurface::TMCToMU	(	TSLTMC	x1,
		TSLTMC	y1,
		double *	x2,
		double *	y2 ) const

Converts from internal co-ordinate to user unit co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

x1	X TMC co-ordinate
y1	Y TMC co-ordinate
x2	Storage for X map unit co-ordinate.
y2	Storage for Y map unit co-ordinate.

Returns: true on success, false otherwise.

◆ TMCToUU()

bool TSLDrawingSurface::TMCToUU	(	TSLTMC	x1,
		TSLTMC	y1,
		double *	x2,
		double *	y2 ) const

Converts from internal co-ordinate to user unit co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	Internal co-ordinate
(x2,y2)	Storage for user unit co-ordinate.

Returns: true on success, false otherwise.

◆ updateEntityExtent()

bool TSLDrawingSurface::updateEntityExtent	(	TSLEntity *	entity,
		const char *	layerName )

Recalculates last rendered extent of a point on the drawingsurface using the currently loaded rendition, without actually rendering it.

After changing attributes of some objects, such as symbol style and text font, their extent may change. Since the extent of text and some symbol objects can only be know at rendering time (due to raster fonts etc), their extent may need to be updated by performing a dummy render. This is also necessary after a text objects string has been changed. This is only necessary for text and symbol entities.

If the entity was retrieved from a data layer (e.g. a TSLMapDataLayer), then the name given to the layer when it was added to this drawing surface should be specified in order to ensure the extent is updated correctly.

Parameters

entity	Entity whose extent to update.
layerName	The name of the data layer in this drawing surface that contains the entity.

Returns: true on success, false otherwise.

◆ userUnitOrigin() [1/2]

void TSLDrawingSurface::userUnitOrigin	(	double	x_origin,
		double	y_origin )

Set origin of user unit coordinate system.

This method defines the position of the user units origin in the map output co-ordinate space.

Parameters

(x_origin,y_origin) Co-ordinate of the user units origin in map units.

◆ userUnitOrigin() [2/2]

void TSLDrawingSurface::userUnitOrigin ( TSLUUEnum origin_enum )

Defines the position of the user units origin.

This method allows the origin to be set to some typical standard values which are calculated according to the current map loaded.

Parameters

origin_enum

Point in the map to be set for the user unit origin. The value can be:

TSLUUBottomLeft to set the bottom left corner of the map as the centre of the user unit co-ordinate space,
TSLUUCentre to set the centre of the map as the centre of the user unit co-ordinate space,
TSLUUTopRight to set the top right corner of the map as the centre of the user unit co-ordinate space.

◆ userUnits() [1/2]

double TSLDrawingSurface::userUnits ( )

Query number of map units per user unit.

This method returns the number of map units equating to the a single user unit.

◆ userUnits() [2/2]

void TSLDrawingSurface::userUnits ( double factor )

Set number of map units per user unit.

This method allows the user to inform the TSLDrawingSurface of how many map units equate to a single user unit. Co-ordinate information sent to the TSLDrawingSurface is normally in user units.

This method should be called at the initialisation phase of your application.

Parameters

factor Number of map output co-ordinates for a single user unit.

◆ UUToDU()

bool TSLDrawingSurface::UUToDU	(	double	x1,
		double	y1,
		TSLDeviceUnits *	x2,
		TSLDeviceUnits *	y2 ) const

Convert from user co-ordinate to device co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	User unit co-ordinate
(x2,y2)	Storage for device co-ordinate.

Returns: true on success, false otherwise.

◆ UUToLatLong()

bool TSLDrawingSurface::UUToLatLong	(	double	x,
		double	y,
		double *	latitude,
		double *	longitude,
		bool	local = false,
		bool	boundCheck = true ) const

Convert user unit co-ordinate to latitude/longitude

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x,y)	User unit co-ordinate
(latitude,longitude)	Storage for lat/lon co-ordinate.
local	Indicates whether the lat/lon co-ordinate is in WGS84 or the local datum.
boundCheck	When the initial coordinates are outside of the map extent, the lat/lon returned could be invalid. When this flag is true, a check for invalid results is performed. This check will double the processing time required by the method, but return a validated status code. If the specified coordinate is guaranteed to be within the map extent, then this flag may be turned off.

Returns: true on success, false otherwise.

◆ UUToMU()

bool TSLDrawingSurface::UUToMU	(	double	x1,
		double	y1,
		double *	x2,
		double *	y2 ) const

Convert user unit co-ordinate to map units.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	User unit co-ordinate
(x2,y2)	Storage for map unit co-ordinate.

Returns: true on success, false otherwise.

◆ UUToTMC()

bool TSLDrawingSurface::UUToTMC	(	double	x1,
		double	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Convert from user unit co-ordinate to an internal co-ordinate.

This method uses the currently loaded transformations for the last TSLMapDataLayer that was added to the Drawing Surface. If this is invalid, then the method returns false.

Parameters

(x1,y1)	User unit co-ordinate.
(x2,y2)	Storage for internal co-ordinate.

Returns: true on success, false otherwise.

◆ wndResize()

bool TSLDrawingSurface::wndResize	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLDeviceUnits	x2,
		TSLDeviceUnits	y2,
		bool	auto_redraw = true,
		TSLResizeActionEnum	action = TSLResizeActionNone )

The user application should call this function on a window resize.

This methods informs the TSLDrawingSurface of a change in size of the attached window handle. If the handle is resized and the TSLDrawingSurface is not informed then the displayed area will remain the same though it may be clipped if the attached handle is reduced in size. All input co-ordinates are given in device units; this is typically in pixels.

Optionally, the uuExtent may be adjusted to fit the new window size. The action parameter determines what should happen to the uuExtent. This is the recommended way to handle this situation since the user unit extent and window extent are not independent.

Note: when the Drawing Surface is first attached to a handle it must be given the co-ordinates of the area that it is to display. This is not necessarily the full area of the handle.

Parameters

(x1,y1)	Top left co-ordinate (in device units) of the area to draw. For the OpenGL surface 0,0 is the bottom left corner, y positive upwards. For all other drawing surfaces 0,0 is the top-left corner, y positive downwards.
(x2,y2)	Bottom right co-ordinate (in device units) of the area to draw. For the OpenGL surface 0,0 is the bottom left corner, y positive upwards. For all other drawing surfaces 0,0 is the top-left corner, y positive downwards.
auto_redraw	If true, will result in the whole drawing surface area being redrawn.
action	One of TSLResizeActionEnum values. Determines if the uuExtent is adjusted automatically. Typically, this is set to TSLResizeActionMaintainTopLeft. The default value, for compatibility is TSLResizeActionNone. A map using the Dynamic Arc coordinate system, with the TSLOptionAdjustForDynamicArc option set on the Drawing Surface, causes the action argument to behave differently than for other configurations: TSLResizeActionNone behaves similarly to TSLResizeActionMaintainCentre. TSLResizeActionMaintainTopLeft, TSLResizeActionMaintainTopRight, TSLResizeActionMaintainBottomLeft, TSLResizeActionMaintainBottomRight may not maintain the corner absolutely when resizing on the y axis.

Returns: true on success, false otherwise.

◆ zoom()

bool TSLDrawingSurface::zoom	(	double	percent,
		bool	zoom_in,
		bool	auto_redraw = true )

Zoom current view in or out.

This method will cause the TSLDrawingSurface to zoom based on the percentage value 'percent'. If 'auto_redraw' it true, then the TSLDrawingSurface will automatically draw the new requested area on the window handle to which the TSLDrawingSurface is attached.

Note: The zoom may cause the extent of the MapLink map data to overflow the extent of TMC coordinate space. In this case, the zoom operation is not applied and the function returns false.

Parameters

percent	The factor given is a percentage of the current amount of map displayed. Any value greater than 0 is valid.
zoom_in	The method will apply a zoom in if this argument is equal to true, or a zoom out if it is equal to false.
auto_redraw	If true, the TSLDrawingSurface redraws automatically.

Returns: true on success, false otherwise.

Detailed Description

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ TSLDrawingSurface()

◆ ~TSLDrawingSurface()

Member Function Documentation

◆ cleanup()

◆ clearAllRendering()

◆ clearDynamicColours()

◆ clearFillList()

◆ clearFontList()

◆ clearLineList()

◆ clearSymbolList()

◆ clone()

◆ copy()

◆ createFontID()

◆ createFontSymbolID()

◆ createRasterBuffer()

◆ createRasterSymbolID()

◆ createStandardFillID()

◆ createStandardLineID()

◆ createSVGSymbolID()

◆ createSymbolFillID()

◆ createSymbolIDFromSymbol()

◆ createSymbolLineID()

◆ declutterIsVisible()

◆ disableAntiAliasFonts()

◆ drawDU()

◆ drawUU()

◆ DUToLatLong()

◆ DUToMU()

◆ DUToTMC()

◆ DUToUU()

◆ enableAntiAliasFonts()

◆ findEntityDU()

◆ findEntityUU()

◆ findSelectedEntityDU()

◆ findSelectedEntityUU()

◆ getColourIndices()

◆ getCoordinateProvidingLayer() [1/2]

◆ getCoordinateProvidingLayer() [2/2]

◆ getDeclutterRange()

◆ getDeviceCapabilities() [1/2]

◆ getDeviceCapabilities() [2/2]

◆ getDUExtent()

◆ getFillStyleIndices()

◆ getFontStyleIndices()

◆ getIDOfNearestColour()

◆ getLineStyleIndices()

◆ getMUExtent()

◆ getSymbolStyleIndices()

◆ getTiledBufferController()

◆ getTMCExtent()

◆ getUUExtent()

◆ getViewedLatLongRange()

◆ latLongToDU()

◆ latLongToMU()

◆ latLongToTMC()

◆ latLongToUU()

◆ loadStandardConfig()

◆ MUToDU()

◆ MUToLatLong()

◆ MUToTMC()

◆ MUToUU()

◆ pan() [1/2]

◆ pan() [2/2]

◆ query() [1/2]

◆ query() [2/2]

◆ redraw()

◆ removeFillStyle()

◆ removeFontStyle()

◆ removeLineStyle()

◆ removeSymbolStyle()

◆ reset()

◆ resize()

◆ rotate()

◆ rotation()

◆ setDeclutterRange()