envitia::maplink::earth::Surface Class Reference

Inheritance diagram for envitia::maplink::earth::Surface:

Detailed Description

Base class for displaying data to a user supplied window.

The Surface component is the common functionality used for all drawing surfaces. It is an abstract class and cannot be instantiated directly.

Instead one of the derivative classes must be created.

This class provides the following capabilities

• Connection of the Surface to a user window
• Management of data layers
• Manipulation of the rendering of features in the map layers
• Control of the visibility of features in the map layers
• Miscellaneous methods

Drawing methods and view management are provided by the derived classes.

A Surface must be connected to a user-supplied window or other rendering handle before anything will be displayed. It does not create a window of its own. This allows the user to attach a drawing surface to a wide range of application toolkits and architectures.

A Surface will display data from any data layers that are connected to it. The ordering and visibility of the data layers used in the Surface are under the control of the user. Data layer management methods include:

• addDataLayer
• removeDataLayer
• bringInFrontOf
• bringToFront
• sendToBackOf
• sendToBack
• getDataLayerProps
• setDataLayerProps

The background colour of the Surface may be defined by the method setBackgroundColour. To make the TSLDrawingSurface transparent, the method 'clearBackgroundColour' may be called. This allows the user application to draw under the TSLDrawingSurface without the image being erased when the TSLDrawingSurface is drawn.

The rendering of map features within the surface can be modified, and will override any rendering information held within a data layer for the modified features. Feature rendering configuration methods include:

• loadRendering
• saveRendering
• setFeatureRendering
• getFeatureRendering
• clearFeatureRendering

The visibility of individual map features within the TSLDrawingSurfaceBase can be modified using the following methods:

• loadDeclutter
• saveDeclutter
• setDeclutterRange
• setDeclutterStatus

setDeclutterStats may be used to declutter individual features, or groups of features.

A drawing surface internally has two sets of declutter settings, a global list that is applied to all data layers in the drawing surface, and a per-layer list that applies to a single data layer that inherits and extends the global list. When modifying declutter settings using the above methods the application can control whether the setting should be set on the global list (and thus apply to all layers in the drawing surface) or a specific data layer's list through the layer name argument of each method.

Thread Safety

MapLink can be used in multiple threads if a degree of care is taken by the user.

The principle rule is that Drawing surfaces and data layers must not be shared between threads.

Additionally loading of the Coordinate Systems and adding or removing coordinate systems is not thread safe.

OS Specific Types

The types used to return OS specific drawing are as follows:

TSLDeviceContext : Windows 'HDC'. TSLWindowHandle : Windows 'HWND'. TSLBitmapHandle : Windows 'HBITMAP', X11 a pointer to a structure declared in tslplatformtypes.h. TSLDrawableHandle : X11 'Drawable'. TSLVisualHandle : X11 'Visual *'. TSLColourmapHandle : X11 'Colormap'. TSLScreenHandle : X11 'Screen *'. TSLDisplayHandle : X11 'Display *'.

If you pass a specific OS type to a method or you are querying a method which returns an OS specific type as defined above you may need to cast the result or argument to the type expected.

Public Member Functions
TSLDrawingSurfaceTypeEnum	type () const
	The type of the drawing surface.
void	attach (TSLDeviceContext handle)
void	attach (TSLWindowHandle handle)
void	attach (Display *x11Display, TSLDrawableHandle handle)
void	detach ()
bool	addDataLayer (TSLDataLayer *layer, const char *layerName)
bool	removeDataLayer (const char *layerName)
int	getNumDataLayers () const
	Query the number of data layers attached to this surface.
TSLDataLayer *	getDataLayer (const char *layerName)
bool	getDataLayerInfo (int layerIndex, TSLDataLayer **layer, const char **layerName) const
bool	bringToFront (const char *layerName)
bool	bringInFrontOf (const char *layerName, const char *targetLayerName)
bool	sendToBack (const char *layerName)
bool	sendToBackOf (const char *layerName, const char *targetLayerName)
bool	getDataLayerProps (const char *layerName, TSLPropertyEnum propertyId, TSLPropertyValue *value)
bool	setDataLayerProps (const char *layerName, TSLPropertyEnum propertyId, TSLPropertyValue value)
bool	forceLayer (const char *dataLayerName, const char *detailLayerName)
TSLSimpleString	queryActiveLayer (const char *dataLayerName) const
bool	queryActiveLayer (const char *dataLayerName, char *detailLayerName, int detailLayerNameSize)
bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)
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
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	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)
bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)
bool	loadRendering (const char *filename)
TSLPickResultSet *	pick (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, TSLPickSelector *selector=0)
TSLPickResultSet *	pick (const char *layerName, TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, TSLPickSelector *selector=0)
bool	clearAllDeclutterData (const char *layerName=0)
bool	clearDeclutterData (const char *featureName, const char *layerName=0)
bool	copyDeclutterData (const char *srcFeatureName, const char *dstFeatureName, const char *srcLayerName=0, const char *dstLayerName=0)
bool	getDeclutterStatus (const char *featureName, TSLDeclutterStatusResultEnum *value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	getDeclutterStatus (TSLFeatureID featureId, TSLDeclutterStatusResultEnum *value, const char *dataLayerName, const char *detailLayerName=0)
bool	setDeclutterStatus (const char *featureName, TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	setDeclutterStatus (TSLFeatureID featureId, TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	setDeclutterStatusOnAllFeatures (TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	loadDeclutter (const char *filename)
bool	saveDeclutter (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)
bool	clearBackgroundColour ()
bool	getBackgroundColour (TSLStyleID *value)
bool	setBackgroundColour (TSLStyleID value)
bool	setBackgroundColour (TSLRGBA colour)
TSLRGBA	getBackgroundColour () const
void	setOption (TSLOptionEnum option, bool value)
bool	getOption (TSLOptionEnum option)
TSLRGBA	getColourValue (TSLStyleID colour) const
bool	getColourValue (int colour, unsigned char &r, unsigned char &g, unsigned char &b) const
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)
bool	fontStyleValue (int index, int colour, TSLBitmapHandle bitmap, TSLSimpleString *fontName=0, const char *outputString=0, TSLSimpleString *section=0)
bool	getFontStyleIndices (int **indices, int *num)
bool	getSymbolStyleIndices (int **indices, int *num)
void	userWord (void *ptr) const
void *	userWord () const
	Returns a pointer to the user data stored on the drawing surface.
void	id (int id_)
int	id () const
virtual	~Surface ()

Static Public Member Functions
static TSLStyleID	getIDOfNearestColour (int r, int g, int b)
static bool	addLoader (TSLFileLoader *loader)
static TSLFileLoader *	getLoader ()
static bool	addPathList (TSLPathList *pathList)
static bool	loadStandardConfig (const char *path=0, bool delayLoadIncludes=false)
static bool	setupColours (const char *filename)
static bool	setupSymbols (const char *filename, bool delayLoadIncludes=false)
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 void	cleanup ()

Protected Member Functions
	Surface ()

Protected Attributes
void *	m_p

Constructor & Destructor Documentation

~Surface()

virtual envitia::maplink::earth::Surface::~Surface ( )

virtual

Surface()

envitia::maplink::earth::Surface::Surface ( )

protected

Member Function Documentation

addDataLayer()

bool envitia::maplink::earth::Surface::addDataLayer	(	TSLDataLayer *	layer,
		const char *	layerName )

Add a TSLDataLayer to Drawing Surface.

The provided layer will be added to the surface, and displayed on top of any existing layers.

When the surface is rendered/drawn any visible data layers will be rendered to the attached handle/window.

Calling addDataLayer may change the coordinate providing layer. The default coordinate providing layer is the last layer added that reports itself to be coordinate providing.

Most data layers may be added to multiple drawing surfaces at once. The application is responsible for ownership/memory management of data layers, however layers may be destroyed without explicitly removing them from the surface.

Parameters

layer	The layer to add. The application retains ownership of the layer.
layerName	A user defined name for the layer within this surface.

Returns

true if the layer was added, false otherwise.

addFeatureRendering()

bool envitia::maplink::earth::Surface::addFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID )

Adds feature rendering.

This method allows the user to add a new feature to the rendering list. If a rendering style for the feature name already exists, it will be cleared, otherwise a new style will be created.

When MapLink is rendering a feature, it first looks at whether the entity has an attribute set. If so, then it tries to apply that attribute set and render the entity. If not, then it uses the feature id of the entity to index into the rendering information loaded into the drawing surface. If there is no rendering information in the TSLDrawingSurface, then it defaults to the rendering information stored with the TSLDataLayer.

If an entity has no attribute set or feature id, then the parent is recursively queried for attribute set and feature code.

If neither an entity, nor any of its parents have attribute sets or feature id, then the entity will not be rendered.

Parameters

featureName	Feature class name to which the rendering style is applied.
featureID	Numeric ID of feature class

Returns

true if the feature was added, false otherwise.

addLoader()

static bool envitia::maplink::earth::Surface::addLoader ( TSLFileLoader * loader )

static

The application can provide a file loader for drawing surfaces to use when loading data.

If addLoader has not been called when a loader is needed, the surface will create a TSLFileLoaderBlocking.

If a loader is already instantiated, it will be replaced by the one provided.

Typically, addLoader would be called to add a TSLFileLoaderMT so that an application can load data in a background thread whilst continuing to respond to user input, or a TSLFileLoaderRemote so that an application can load data from an internet server.

If addLoader is called, the surfaces take a reference to the loader but does not take ownership of it. The loader could be added to data layers as well as the surface. The application must ensure that the loader remains in existence while the surface has a reference to it, and the application must delete the loader when it is no longer needed.

But if the surface creates a TSLFileLoaderBlocking because no loader was added, the surface will own the loader and will delete it when necessary. In fact, all surfaces share a single static loader which is created when first needed and destroyed when no longer needed.

The loader is always used in synchronous mode.

The loader is shared between drawing surfaces. The adding of a loader is not thread safe. Either add the loader before starting any threads that use Drawing Surfaces or block the use of all Drawing Surfaces while adding a loader. This is only necessary if you are using Drawing Surfaces in separate threads.

Parameters

loader

the loader to add. Pass NULL to reset to the default loader.

Returns

true if successful.

addPathList()

static bool envitia::maplink::earth::Surface::addPathList ( TSLPathList * pathList )

static

Add a TSLPathList object to all surfaces. This will be used for finding files, for example in setupColours.

The path list is shared between drawing surfaces. The adding of a path list is not thread safe. Either add the path list before starting any threads that use Drawing Surfaces or block the use of all Drawing Surfaces while adding a path list. This is only necessary if you are using Drawing Surfaces in separate threads.

The path list object is only thread safe if it is not modified while in use.

Note

The surface does not take ownership of the path list, so the application must ensure it is not deleted while any drawing surface exists.

Parameters

pathList

The path list to add. Pass NULL to remove the path list from the drawing surfaces.

Returns

true on a successful addition, false otherwise.

attach() [1/3]

void envitia::maplink::earth::Surface::attach	(	Display *	x11Display,
		TSLDrawableHandle	handle )

Attach the drawing surface to a drawable

This method is X11 specific.

After calling this method the application should

• Call wndResize to adjust the view dimensions
• Call setDeviceCapabilites if the default need to be adjusted

Parameters

handle

The drawable to attach.

attach() [2/3]

void envitia::maplink::earth::Surface::attach

(

TSLDeviceContext

handle

)

Attach the drawing surface to a device context (HDC).

This method is Microsoft Windows specific.

After calling this method the application should

• Call wndResize to adjust the view dimensions
• Call setDeviceCapabilites if the default need to be adjusted

Parameters

handle

The HDC to attach.

attach() [3/3]

void envitia::maplink::earth::Surface::attach

(

TSLWindowHandle

handle

)

Attach the drawing surface to a window handle (HWND).

This method is Microsoft Windows specific.

After calling this method the application should

• Call wndResize to adjust the view dimensions
• Call setDeviceCapabilites if the default need to be adjusted

Parameters

handle

The HWND to attach.

bringInFrontOf()

bool envitia::maplink::earth::Surface::bringInFrontOf	(	const char *	layerName,
		const char *	targetLayerName )

Move a data layer in front of another.

This method allows the display order of the attached TSLDataLayer instances to be modified. The TSLDataLayer identified by layerName is moved so that it is drawn immediately in front of the layer identified by targetLayerName.

Parameters

layerName	The name of the layer to move, as passed to addDataLayer.
targetLayerName	The name of the layer to move in front of.

Returns

true if the layer was moved, false otherwise.

bringToFront()

bool envitia::maplink::earth::Surface::bringToFront

(

const char *

layerName

)

Move Data Layer to the top of the Drawing Surface display list.

This method allows the display order of the attached TSLDataLayer instances to be modified. The specified TSLDataLayer instance will be drawn on top of all other TSLDataLayer instances attached to this Surface.

Parameters

layerName

The name of the layer to move, as passed to addDataLayer.

Returns

true if the layer was moved, false otherwise.

cleanup()

static void envitia::maplink::earth::Surface::cleanup ( )

static

Free configuration settings.

This method should be called once before exiting the application which instantiates any number of drawing surfaces. 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.

clearAllDeclutterData()

bool envitia::maplink::earth::Surface::clearAllDeclutterData

(

const char *

layerName = 0

)

Clears all feature decluttering on the Surface.

Parameters

layerName

Name of the layer to clear the decluttering on. If this is NULL, feature decluttering is cleared from all layers in the drawing surface.

Returns

true if the declutter data was cleared, false otherwise.

clearBackgroundColour()

bool envitia::maplink::earth::Surface::clearBackgroundColour

(

)

Clears the background colour of the Surface.

If the background colour is cleared and a draw request is made which specifies the clear flag, then under Windows, the Drawing Surface will clear the area using a white brush; under X the Drawing Surface will clear the area of (i) a window using the 'background_pixel' / 'background_pixmap' attributes or (ii) a pixmap using WhitePixel of the display.

Returns true if the background colour was cleared, false otherwise.

clearDeclutterData()

bool envitia::maplink::earth::Surface::clearDeclutterData	(	const char *	featureName,
		const char *	layerName = 0 )

Clear feature decluttering.

This method removes the declutter data for the named feature. If there is no declutter data for a given feature it will always be visible.

Parameters

featureName	Name of the feature for which to clear the declutter settings
layerName	Name of the layer to clear the decluttering on. If this is NULL, the declutter settings for the feature will be cleared from all layers in the drawing surface.

Returns

true if the declutter data was cleared, false otherwise.

clearFeatureRendering()

bool envitia::maplink::earth::Surface::clearFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID )

Clear feature rendering.

This method removes the rendering style information that has been previously set for a given feature, by one of the 'setRendering' methods.

When MapLink is rendering a feature, it first looks at whether the entity has an attribute set. If so, then it tries to apply that attribute set and render the entity. If not, then it uses the feature id of the entity to index into the rendering information loaded into the drawing surface. If there is no rendering information in the drawing surface, then it defaults to the rendering information stored with the TSLDataLayer.

If an entity has no attribute set or feature id, then the parent is recursively queried for attribute set and feature code.

If neither an entity, nor any of its parents have attribute sets or feature id, then the entity will not be rendered.

Parameters

featureName	Feature class name from which the rendering style information is removed. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID

Returns

true if the rendering was cleared, false otherwise.

copyDeclutterData()

bool envitia::maplink::earth::Surface::copyDeclutterData	(	const char *	srcFeatureName,
		const char *	dstFeatureName,
		const char *	srcLayerName = 0,
		const char *	dstLayerName = 0 )

Copy feature decluttering.

This method copies the declutter information for one feature to another feature.

If no declutter data for the source feature exists then the declutter information for the destination feature will be cleared as if clearDeclutterData was called for that feature.

Any existing declutter data for the destination feature will be overwritten.

Parameters

srcFeatureName	Name of the source feature.
dstFeatureName	Name of the destination feature.
srcLayerName	Name of the source layer from which to read the declutter data for the source feature. If this is NULL, the declutter data for the source feature is read from the global declutter settings.
dstLayerName	Name of the destination layer for which to set the declutter data for the destination feature. If this is NULL, the declutter data for the destination feature is set on all data layers in the drawing surface.

Returns

true if the declutter data was copied, false otherwise.

createFontID()

TSLStyleID envitia::maplink::earth::Surface::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 )

Add a font definition

This method allows an application to create a font style at runtime. This is the equivalent of editing tslfonts.dat

Parameters

name	The font name, or filename.
meaningOfName	The type of font.
fontWeight	The font weight.
italic	Whether the font should be rendered italic.
underline	Whether the font should be rendered underlined.
antiAliased	Whether the font should be rendered with anti-aliasing.
memoryBlock	If provided must contain the font file, loaded into memory. If not provided the font will be loaded using the name parameter.
memoryBlockSize	The size of memoryBlock, or zero if memoryBlock is null

Returns

The created font, or -1 on error.

detach()

void envitia::maplink::earth::Surface::detach

(

)

Detach the drawing surface from the rendering handle

The drawing surface should be considered invalid until it has been re-attached to a rendering handle. No methods are expected to function when in a detached state.

The user is responsible for the management of the detached HDC/Pixmap/window.

fontStyleValue()

bool envitia::maplink::earth::Surface::fontStyleValue	(	int	index,
		int	colour,
		TSLBitmapHandle	bitmap,
		TSLSimpleString *	fontName = 0,
		const char *	outputString = 0,
		TSLSimpleString *	section = 0 )

Query example text rendering used by the drawing surface.

This method populates the specified bitmap with a sample of the specified text style. The bitmap is not cleared before drawing the text. The height of the bitmap is used define the height of the text. The text displayed is either the specified outputString, or the font name if no string is passed.

If required, the name of the font may be returned through the fontName parameter.

Parameters

index	Index of a font style
colour	Colour to display the text
bitmap	Bitmap to populate with text
fontName	Populated by the base name of the font (optional)
outputString	String to be displayed, otherwise font name is used (optional)
section	If provided this will be populated with the section heading that this font style appears under

Returns

true on success, false otherwise.

forceLayer()

bool envitia::maplink::earth::Surface::forceLayer	(	const char *	dataLayerName,
		const char *	detailLayerName )

Force a data layer to display a specific detail layer.

This method forces the Surface to use a specific detail layer for display purposes, rather than the layer automatically chosen by the Surface.

The concept of a 'detail layer' will vary based on the data layer type. For instance for a TSLMapDataLayer they are the layers configured within MapLink Studio, but in a TSLCADRGDataLayer they are the display scales within the loaded data. See the data layer's API documentation for more information.

Parameters

dataLayerName	Name of the data layer within this Surface.
detailLayerName	Detail layer name within the data layer.

Returns

true on success, false otherwise.

getBackgroundColour() [1/2]

TSLRGBA envitia::maplink::earth::Surface::getBackgroundColour

(

)

const

The background colour of the surface.

Returns

The background colour of the surface.

getBackgroundColour() [2/2]

bool envitia::maplink::earth::Surface::getBackgroundColour

(

TSLStyleID *

value

)

Returns the background colour of the Surface.

This method returns the background colour of the surface. This may be an index to the colour list, or an RGB colour. See tslcolourhelper.h for more information.

Parameters

value

Storage for the background colour. If set to -1 there is not currently a background colour set.

Returns

true on success, false otherwise.

getColourValue() [1/2]

bool envitia::maplink::earth::Surface::getColourValue	(	int	colour,
		unsigned char &	r,
		unsigned char &	g,
		unsigned char &	b ) const

Returns the RGB value that corresponds to the given colour index according to the current drawing surface's palette.

If the given colour is an RGB colour and not a colour index, this function is equivalent to using the TSLDecomposeRGB macro.

Parameters

colour	The colour index to query
r	Will be set to the red component of the queried colour
g	Will be set to the green component of the queried colour
b	Will be set to the blue component of the queried colour

Returns

true if the colour was queried, false otherwise.

getColourValue() [2/2]

TSLRGBA envitia::maplink::earth::Surface::getColourValue

(

TSLStyleID

colour

)

const

Returns the RGB value that corresponds to the given colour index according to the current drawing surface's palette.

If the given colour is an RGB colour and not a colour index, this function will return the input colour directly.

Parameters

colour

The colour index to query.

Returns

The requested colour value.

getDataLayer()

TSLDataLayer * envitia::maplink::earth::Surface::getDataLayer

(

const char *

layerName

)

Query a data layer from the surface.

Parameters

layerName

The user defined name of the layer within this surface.

Returns

A pointer to the requested layer, or null on error.

getDataLayerInfo()

bool envitia::maplink::earth::Surface::getDataLayerInfo	(	int	layerIndex,
		TSLDataLayer **	layer,
		const char **	layerName ) const

Query information about a data layer.

This method allows an application to get the name and pointer of a data layer attached to the drawing surface.

Parameters

layerIndex	The index of the layer to query.
layer	A pointer which will be set to the requested layer.
layerName	A pointer which will be set to the name of the requested layer.

Returns

true if the layer info was queried, false otherwise.

getDataLayerProps()

bool envitia::maplink::earth::Surface::getDataLayerProps	(	const char *	layerName,
		TSLPropertyEnum	propertyId,
		TSLPropertyValue *	value )

Query properties and flags for a data layer.

This method allows the user to get the current property value for the TSLDataLayer.

Default values for the properties are documented in TSLPropertyEnum.

Parameters

layerName	User defined name of a TSLDataLayer.
propertyId	The property to query.
value	Storage for value of this property.

Returns

true on success, false otherwise.

getDeclutterStatus() [1/2]

bool envitia::maplink::earth::Surface::getDeclutterStatus	(	const char *	featureName,
		TSLDeclutterStatusResultEnum *	value,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Queries feature decluttering settings for a given feature.

This method gets the visibility status of a feature within the Surface. The visibility for a feature is either always ON, always OFF, or automatically set by the Surface based on the current resolution.

Passing a partial feature class name gets the visibility setting for the set of all subclasses. For example, getting "VMAP0.Contour Line (Land)" will return a value of ON if all contour lines are on, OFF if all contour lines are off, AUTOMATIC if all contour lines are automatically decluttered or PARTIAL if the contour lines have a mixture of statuses.

Applications should generally always pass a layer name to this method, as the declutter status of a given feature may be different for each layer that contains that feature.

Parameters

featureName	Name of the feature type to get the status from.
value	Storage for current status.
dataLayerName	The data layer to get the decluttering for. If this is NULL the declutter status is read from the global declutter list, which may differ from the declutter status of the layers in the drawing surface.
detailLayerName	The detail layer to get the decluttering for - default to 0 to get the decluttering for all detail layers

Returns

true on success, false otherwise.

getDeclutterStatus() [2/2]

bool envitia::maplink::earth::Surface::getDeclutterStatus	(	TSLFeatureID	featureId,
		TSLDeclutterStatusResultEnum *	value,
		const char *	dataLayerName,
		const char *	detailLayerName = 0 )

Queries feature decluttering settings for a given feature by its identifier.

This method gets the visibility status of a feature within the Surface. The visibility for a feature is either always ON, always OFF, or automatically set by the Surface based on the current resolution.

When getting the status of a singular feature on a data layer and the feature ID is known then this method is more efficient than the alternative getDeclutterStatus that takes the feature name rather than the feature ID.

Parameters

featureId	ID of the feature type to get the status from.
value	Storage for current status.
dataLayerName	The data layer to get the decluttering for. This cannot be NULL.
detailLayerName	the detail layer to get the decluttering for - default to 0 to get the decluttering for all detail layers

Returns

true on success, false otherwise.

getFeatureRendering() [1/4]

bool envitia::maplink::earth::Surface::getFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeBool	attribute,
		bool *	result ) const

Gets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to get
result	Storage for returned rendering attribute value

Returns

true if rendering attribute successfully read and stored in result, false otherwise.

getFeatureRendering() [2/4]

bool envitia::maplink::earth::Surface::getFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeDouble	attribute,
		double *	result ) const

Gets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to get
result	Storage for returned rendering attribute value

Returns

true if rendering attribute successfully read and stored in result, false otherwise.

getFeatureRendering() [3/4]

bool envitia::maplink::earth::Surface::getFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeInt	attribute,
		int *	result ) const

Gets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to get
result	Storage for returned rendering attribute value

Returns

true if rendering attribute successfully read and stored in result, false otherwise.

getFeatureRendering() [4/4]

bool envitia::maplink::earth::Surface::getFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributes *	result ) const

Gets rendering for a specified feature class.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
result	Storage for returned rendering attribute values

Returns

true if rendering attributes successfully read and stored in result, false otherwise.

getFontStyleIndices()

bool envitia::maplink::earth::Surface::getFontStyleIndices	(	int **	indices,
		int *	num )

Query font style indices.

Queries font style indices specified in the font style file last loaded using setupFontStyles.

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 envitia::maplink::earth::Surface::getIDOfNearestColour ( int r, int g, int b )

static

Find a colour in the colour list.

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, or -1 on error.

getLoader()

static TSLFileLoader * envitia::maplink::earth::Surface::getLoader ( )

static

Query the file loader used by the drawing surface

Returns

The loader passed to addLoader, or the default loader if none has been set.

getNumDataLayers()

int envitia::maplink::earth::Surface::getNumDataLayers

(

)

const

Query the number of data layers attached to this surface.

getOption()

bool envitia::maplink::earth::Surface::getOption

(

TSLOptionEnum

option

)

Query a drawing surface option/flag

Parameters

option

The option to query.

Returns

The value of the option.

getSymbolStyleIndices()

bool envitia::maplink::earth::Surface::getSymbolStyleIndices	(	int **	indices,
		int *	num )

Query symbol style indices.

Queries symbol style indices specified in the symbol style file last loaded using setupSymbols.

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.

id() [1/2]

int envitia::maplink::earth::Surface::id

(

)

const

Returns the user drawing surface ID. If no ID has been set, a number less than 0 that uniquely identifies the drawing surface will be returned instead.

id() [2/2]

void envitia::maplink::earth::Surface::id

(

int

id_

)

Sets the user drawing surface ID. Negative values are reserved.

Parameters

id_	the user drawing surface ID to be set.

loadDeclutter()

bool envitia::maplink::earth::Surface::loadDeclutter

(

const char *

filename

)

Load feature decluttering file.

This method allows the user to load a set of declutter data from a given file. Each Surface may, optionally, declutter features differently from another Surface.

If addPathList or loadStandardConfig has been called then the path list 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

Declutter file name.

Returns

true if the file was found and loaded successfully, false otherwise.

loadRendering()

bool envitia::maplink::earth::Surface::loadRendering

(

const char *

filename

)

Load feature rendering file.

This method allows the user to load a set of rendering data from a given file. Each Surface may, optionally, render data types in different ways from another Surface.

If addPathList or loadStandardConfig has been called then the path list 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.

When MapLink is rendering a feature, it first looks at whether the entity has an attribute set. If so, then it tries to apply that attribute set and render the entity. If not, then it uses the feature id of the entity to index into the rendering information loaded into the Surface. If there is no rendering information in the Surface, then it defaults to the rendering information stored with the TSLDataLayer.

If an entity has neither attribute set nor feature id, then the parent is recursively queried for attribute set and feature code.

If neither an entity, nor any of its parents have attribute sets or feature id, then the entity will not be rendered.

Parameters

filename

Name of the rendering data file.

Returns

true if file successfully loaded, false otherwise.

loadStandardConfig()

static bool envitia::maplink::earth::Surface::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 path list 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.

pick() [1/2]

TSLPickResultSet * envitia::maplink::earth::Surface::pick	(	const char *	layerName,
		TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture,
		int	depth = -1,
		TSLPickSelector *	selector = 0 )

Pick objects from data layers from specified pixel location.

Only the currently active detail layer for each data layer will be queried.

This method requests all layers to return a set of TSLPickResult objects which allows the user to determine what objects are contained within the specified pick area.

The TSLPickResultSet is only valid for use until the next redraw since the data tiles to which they refer may be removed from memory when caches are 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.

Pick operations may not preserve the original geometry hierarchy in some cases.

Parameters

layerName	The name of the data layer to perform the pick operation on.
x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display 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 TSLEntitySet rather than an entity within the set).
selector	Optional class derived from TSLPickSelector that can be used to further filter the results based on user criteria.

Returns

The return value is a TSLPickResultSet that contains the picked results. The application must call TSLPickResultSet::destroy when the pick results are finished with.

pick() [2/2]

TSLPickResultSet * envitia::maplink::earth::Surface::pick	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture,
		int	depth,
		TSLPickSelector *	selector = 0 )

Pick objects from data layers from specified pixel location.

Only the currently active detail layer for each data layer will be queried.

This method requests all layers to return a set of TSLPickResult objects which allows the user to determine what objects are contained within the specified pick area.

The TSLPickResultSet is only valid for use until the next redraw since the data tiles to which they refer may be removed from memory when caches are 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.

Pick operations may not preserve the original geometry hierarchy in some cases.

Parameters

x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display 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 TSLEntitySet rather than an entity within the set).
selector	Optional class derived from TSLPickSelector that can be used to further filter the results based on user criteria.

Returns

The return value is a TSLPickResultSet that contains the picked results. The application must call TSLPickResultSet::destroy when the pick results are finished with.

queryActiveLayer() [1/2]

TSLSimpleString envitia::maplink::earth::Surface::queryActiveLayer

(

const char *

dataLayerName

)

const

Query the active detail layer for a data layer.

This method gets the name of the current detail layer used by the specified data layer on this Surface.

Parameters

dataLayerName

This is the user defined name of the data layer when it was added to the Drawing Surface, i.e. passed to 'addDataLayer'.

Returns

The name of the active detail layer, for the specified data layer.

queryActiveLayer() [2/2]

bool envitia::maplink::earth::Surface::queryActiveLayer	(	const char *	dataLayerName,
		char *	detailLayerName,
		int	detailLayerNameSize )

Query the active detail layer for a data layer.

This method gets the name of the current detail layer used by the specified data layer on this Surface. The name is copied into the supplied buffer.

Parameters

dataLayerName	This is the user defined name of the data layer when it was added to the Drawing Surface, i.e. passed to 'addDataLayer'.
detailLayerName	Layer name output buffer.
detailLayerNameSize	Size of the buffer

Returns

true on success, false otherwise.

removeDataLayer()

bool envitia::maplink::earth::Surface::removeDataLayer

(

const char *

layerName

)

Remove a named layer from the drawing surface

Parameters

layerName

The name of the layer to remove

Returns

true if the layer was removed, false otherwise.

saveDeclutter()

bool envitia::maplink::earth::Surface::saveDeclutter	(	const char *	filename,
		TSLMapLinkVersion	ver = TSL_CURRENT_MAPLINK_VERSION )

Save feature decluttering file.

This method allows any declutter data that the user has set for a Surface to be saved to the specified file.

Parameters

filename	Declutter file name.
ver	the MapLink version to save as

Returns

true if the file was successfully saved, false otherwise.

saveRendering()

bool envitia::maplink::earth::Surface::saveRendering	(	const char *	filename,
		TSLMapLinkVersion	ver = TSL_CURRENT_MAPLINK_VERSION )

Save rendering file.

This method allows any rendering information that the user has set up for a TSLDrawingSurface to be saved to the specified file.

Parameters

filename	Name of the rendering data file.
ver	The MapLink version to save the file as.

Returns

true if the rendering was saved, false otherwise.

sendToBack()

bool envitia::maplink::earth::Surface::sendToBack

(

const char *

layerName

)

Move Data Layer to the bottom of the Drawing Surface display list.

This method allows the specified TSLDataLayer to be placed behind all other attached TSLDataLayer instances attached to this Surface.

Parameters

layerName

Name of a TSLDataLayer instance, as passed to addDataLayer.

Returns

true if the layer was moved, false otherwise.

sendToBackOf()

bool envitia::maplink::earth::Surface::sendToBackOf	(	const char *	layerName,
		const char *	targetLayerName )

Move a data layer behind another.

This method allows the display order of the attached TSLDatalayer instances to be modified. The TSLDataLayer object layerName is moved so that it is drawn immediately behind the layer identified by targetLayerName.

Parameters

layerName	The name of the layer to move, as passed to addDataLayer.
targetLayerName	The name of the layer to place the modified layer behind.

Returns

true if the layer was moved, false otherwise.

setBackgroundColour() [1/2]

bool envitia::maplink::earth::Surface::setBackgroundColour

(

TSLRGBA

colour

)

Set the background colour of the Surface

Depending on the surface implementation the alpha component of the colour may be respected, or may be ignored.

Parameters

colour

The background colour.

Returns

true if the background colour was set, false otherwise.

setBackgroundColour() [2/2]

bool envitia::maplink::earth::Surface::setBackgroundColour

(

TSLStyleID

value

)

Set the background colour of the Surface.

This method sets the colour to be used by the TSLDrawingSurface when drawing a background area before the MapLink map data is drawn.

The default for the background colour is either the map background colour (should there be one) or else see the documentation for clearBackgroundColour.

Parameters

value

The background colour.

Returns

true if the background colour was set, false otherwise.

setDataLayerProps()

bool envitia::maplink::earth::Surface::setDataLayerProps	(	const char *	layerName,
		TSLPropertyEnum	propertyId,
		TSLPropertyValue	value )

Set properties and flags for a data layer.

This method allows the user to set the properties for the TSLDataLayer. The properties are specific to this Drawing Surface and will not affect any other Drawing Surface that the named Data Layer is displayed in.

Default values for the properties are documented in TSLPropertyEnum.

Parameters

layerName	User defined name of a TSLDataLayer.
propertyId	Property to be set.
value	New value for this property.

Returns

true on success, false otherwise.

setDeclutterStatus() [1/2]

bool envitia::maplink::earth::Surface::setDeclutterStatus	(	const char *	featureName,
		TSLDeclutterStatusEnum	value,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Set feature decluttering action for a named feature.

This method sets the visibility of a feature within the Surface. If the visibility is set to automatic the Surface will determine when a feature should be made visible or invisible based upon on a resolution factor set in the setDeclutterRange method.

Passing a partial feature class name allows decluttering of the set of all subclasses. For example, decluttering "VMAP0.Contour Line (Land)" will declutter all VMAP0 contour lines.

Parameters

featureName	Name of the feature class.
value	Status value.
dataLayerName	Name of the layer to set the decluttering on. If this is NULL then the name feature(s) are decluttered on all layers in the drawing surface.
detailLayerName	name of the detail layer to set the decluttering on - default is 0 to set decluttering for all detail layers in which the feature appears

Returns

true on success, false otherwise.

setDeclutterStatus() [2/2]

bool envitia::maplink::earth::Surface::setDeclutterStatus	(	TSLFeatureID	featureId,
		TSLDeclutterStatusEnum	value,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Set feature decluttering action for a feature by its identifier.

This method sets the visibility of a feature within the Surface. If the visibility is set to automatic the Surface will determine when a feature should be made visible or invisible based upon on a resolution factor set in the setDeclutterRange method.

If setting the declutter status of a singular feature and the feature ID is known then this method is more efficient than the alternative setDeclutterStatus that takes the feature name instead of the feature ID.

Applications should generally always pass a layer name to this function. Features in different data layers may have the same feature ID associated with different features as feature IDs are only unique to a data layer. Therefore decluttering features by ID across layers may result in a different feature being decluttered in each layer as the ID maps to a different feature name.

Parameters

featureId	ID of the feature class.
value	Status value.
dataLayerName	Name of the layer to set the decluttering on. If this is NULL, the given feature ID will be decluttered on all layers in the drawing surface.
detailLayerName	name of the detail layer to set the decluttering on - default is 0 to set decluttering for all detail layers in which the feature appears

Returns

true on success, false otherwise.

setDeclutterStatusOnAllFeatures()

bool envitia::maplink::earth::Surface::setDeclutterStatusOnAllFeatures	(	TSLDeclutterStatusEnum	value,
		const char *	dataLayerName = 0,
		const char *	detailLayerName = 0 )

Set feature decluttering action on all features that meet the criteria passed.

This method sets the visibility of a set of features within the Surface. If the visibility is set to automatic the Surface will determine when a feature should be made visible or invisible based upon on a resolution factor set in the setDeclutterRange method.

Parameters

value	Status value.
dataLayerName	Name of the layer to set the decluttering on. Default is 0 i.e. set for all layers.
detailLayerName	Name of the detail layer to set the decluttering on - default is 0 to set decluttering for all detail layers in which the feature appears

Returns

true on success, false otherwise.

setFeatureRendering() [1/4]

bool envitia::maplink::earth::Surface::setFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeBool	attribute,
		bool	value )

Sets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to set
value	New value for rendering attribute

Returns

true if rendering attribute successfully set, false otherwise.

setFeatureRendering() [2/4]

bool envitia::maplink::earth::Surface::setFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeDouble	attribute,
		double	value )

Sets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to set
value	New value for rendering attribute

Returns

true if rendering attribute successfully set, false otherwise.

setFeatureRendering() [3/4]

bool envitia::maplink::earth::Surface::setFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributeInt	attribute,
		int	value )

Sets rendering for a specified feature class.

For further information about what attributes are available, see the setRendering methods on TSLEntity.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
attribute	Type of rendering attribute to set
value	New value for rendering attribute

Returns

true if rendering attribute successfully set, false otherwise.

setFeatureRendering() [4/4]

bool envitia::maplink::earth::Surface::setFeatureRendering	(	const char *	featureName,
		TSLFeatureID	featureID,
		TSLRenderingAttributes *	value )

Sets rendering for a specified feature class.

If a name is specified, then all data layers attached to the drawing surface are searched to provide a mapping to ID. They are searched in rendering order from back to front.

Where possible, it is more efficient for an application to use the featureID directly.

Parameters

featureName	Name of feature class. NULL means use featureID.
featureID	Numeric ID of feature class as stored in TSLEntity::featureID
value	New value for rendering attributes

Returns

true if rendering attributes successfully set, false otherwise.

setOption()

void envitia::maplink::earth::Surface::setOption	(	TSLOptionEnum	option,
		bool	value )

Set a drawing surface option/flag.

Note

Some drawing surface implementations will not support all options.

Parameters

option	The option to set.
value	The new value of the option.

setupColours()

static bool envitia::maplink::earth::Surface::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 drawing surfaces.

If addPathList or loadStandardConfig has been called then the path list 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 envitia::maplink::earth::Surface::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 drawing surfaces.

If addPathList or loadStandardConfig has been called then the path list 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 need to be done only once per application. Calling this more than once will not have any effects on the original fill styles.

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 envitia::maplink::earth::Surface::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 drawing surfaces when rendering text.

If addPathList or loadStandardConfig has been called then the path list 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 needs only to be called once per application. Calling this more than once will not have any effect on the original font list.

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 envitia::maplink::earth::Surface::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 drawing surfaces.

If addPathList or loadStandardConfig has been called then the path list 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 need to be done only once per application. Calling this more than once will not have any effects on the original line styles.

Parameters

filename	Name of the line style file.
delayLoadIncludes	If this flag is set to true the all referenced include files in the lifestyle 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 envitia::maplink::earth::Surface::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 drawing surfaces.

If addPathList or loadStandardConfig has been called then the path list 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 need to be done only once per application. Calling this more than once will not have any effects on the original symbol list.

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.

type()

TSLDrawingSurfaceTypeEnum envitia::maplink::earth::Surface::type

(

)

const

The type of the drawing surface.

userWord() [1/2]

void * envitia::maplink::earth::Surface::userWord

(

)

const

Returns a pointer to the user data stored on the drawing surface.

userWord() [2/2]

void envitia::maplink::earth::Surface::userWord

(

void *

ptr

)

const

Stores a pointer to user data on the drawing surface.

Parameters

ptr	The pointer to the user data.

Member Data Documentation

m_p

void* envitia::maplink::earth::Surface::m_p

protected