TSLAPP6AHelper Class Reference

Detailed Description

The TSLAPP6AHelper class should be used to manipulate the APP6ASymbols. It provides methods for creating symbols as HBITMAPs, Entity Sets or TSLAPP6ASymbol objects.

Either the app6aConfig.csv or 2525bConfig.csv configuration files are required for this class to operate correctly. These files define the symbols for the APP6A or 2525B specifications respectively. These files can normally be found in your MapLink home config folder. During construction of a TSLAPP6AHelper instance an attempt will be made to find and load the app6aConfig.csv file at the default location. If you wish to load the alternate configuration file, specify the full path to the file, including the filename.

Note: There is no internal reference counting provided within the internal implementation; each instance of this call will attempt to load the config file once.

You can check that the configuration file has been successfully loaded by calling the 'valid()' method after construction.

Check the TSLErrorStack::lastError() method for a description of the problem.

Public Member Functions
	TSLAPP6AHelper (const char *configPath="")
void	destroy ()
TSLEntitySet *	getSymbolAsEntitySet (const TSLAPP6ASymbol *symbol)
TSLEntitySet *	getSymbolAsEntitySet (const char *symbol)
bool	getSymbolAsBitmap (const TSLAPP6ASymbol *symbol, TSLBitmapHandle bitmap, bool clear=true)
bool	getSymbolAsBitmap (const char *symbol, TSLBitmapHandle bitmap, bool clear=true)
bool	getSymbolAsBitmap (const TSLEntitySet *es, TSLBitmapHandle bitmap, bool clear=true)
bool	getSymbol (const TSLEntitySet *es, TSLAPP6ASymbol &symbol)
bool	getSymbol (int index, TSLAPP6ASymbol &symbol)
bool	getSymbolFromID (const char *id, TSLAPP6ASymbol &symbol)
bool	isAPP6A (const TSLEntitySet *es)
int	numOfSymbols ()
bool	valid ()
void *	operator new (size_t size) TSL_NO_THROW
void *	operator new (size_t size, char *filename, int line)
bool	getSymbolFromSIDCAPP6A (const char *sidc, TSLAPP6ASymbol &symbol)
bool	getSymbolFromSIDC2525B (const char *sidc, TSLAPP6ASymbol &symbol)

Static Public Member Functions
static void	getDefaultConfigPath (TSLSimpleString &configPath)
static void	setDefaultConfigPath (const char *path)

Protected Member Functions
	~TSLAPP6AHelper ()

Constructor & Destructor Documentation

TSLAPP6AHelper()

TSLAPP6AHelper::TSLAPP6AHelper

(

const char *

configPath = ""

)

Constructor. Use this to create instances of this class.

Parameters

configPath

Can be used to specify a different configuration file location. If left empty the class will attempt to use a default file.

Check the result of 'valid()' to ensure that the configuration file loaded correctly. If false the TSLErrorStack can be queried for a reason for the problem.

~TSLAPP6AHelper()

TSLAPP6AHelper::~TSLAPP6AHelper ( )

protected

Destructor.

This method is protected to force the user to created instances of the helper on the heap. This enables the API redirection to work correctly.

Use 'destroy()' to remove instances of this class.

Member Function Documentation

destroy()

void TSLAPP6AHelper::destroy

(

)

Removes instances of this class. Use this method instead of the 'delete' keyword.

getDefaultConfigPath()

static void TSLAPP6AHelper::getDefaultConfigPath ( TSLSimpleString & configPath )

static

Use this method to query the default location of the configuration file.

Parameters

configPath

: Returns the configuration path (this may be empty).

getSymbol() [1/2]

bool TSLAPP6AHelper::getSymbol	(	const TSLEntitySet *	es,
		TSLAPP6ASymbol &	symbol )

Use this method to populate a TSLAPP6ASymbol object with the information from a valid entity set. This allows symbols that have been placed on the map surface to be reloaded into a TSLAPP6ASymbol object for further manipulation.

Parameters

es	A pointer to the entity set which should be loaded.
symbol	The symbol which should be populated with the information.

Returns

true if successful, false otherwise (You can check TSLErrorStack for a description of the error).

getSymbol() [2/2]

bool TSLAPP6AHelper::getSymbol	(	int	index,
		TSLAPP6ASymbol &	symbol )

Use this method to populate a TSLAPP6ASymbol object with the symbol information add position 'index' in the configuration file.

Parameters

index	The index of the symbol to load.
symbol	The symbol which should be populated with the information.

Returns

true if successful, false otherwise.

getSymbolAsBitmap() [1/3]

bool TSLAPP6AHelper::getSymbolAsBitmap	(	const char *	symbol,
		TSLBitmapHandle	bitmap,
		bool	clear = true )

Use this method to write a valid APP6A string into a bitmap.

NOTE: On X11 targets a typedef has been created for TSLBitmapHandle. The structure needs to be filled in by the caller.

Parameters

symbol	The source APP6A string containing the symbol.
bitmap	The handle to a bitmap object. This must be a HBITMAP.
clear	If set to true the bitmap will be cleared (to white) before it is populated, otherwise the symbol will be drawn over the existing background.

Returns

true if successful, false otherwise (You can check TSLErrorStack for a description of the error).

getSymbolAsBitmap() [2/3]

bool TSLAPP6AHelper::getSymbolAsBitmap	(	const TSLAPP6ASymbol *	symbol,
		TSLBitmapHandle	bitmap,
		bool	clear = true )

Use this method to write a TSLAPP6ASymbol object into a bitmap.

NOTE: On X11 targets a typedef has been created for TSLBitmapHandle. The structure needs to be filled in by the caller.

Parameters

symbol	The source symbol.
bitmap	The handle to a bitmap object. This must be a HBITMAP.
clear	If set to true the bitmap will be cleared (to white) before it is populated, otherwise the symbol will be drawn over the existing background.

Returns

true if successful, false otherwise (You can check TSLErrorStack for a description of the error).

getSymbolAsBitmap() [3/3]

bool TSLAPP6AHelper::getSymbolAsBitmap	(	const TSLEntitySet *	es,
		TSLBitmapHandle	bitmap,
		bool	clear = true )

Use this method to write an TSLEntitySet object into a bitmap.

NOTE: On X11 targets a typedef has been created for TSLBitmapHandle. The structure needs to be filled in by the caller.

Parameters

es	The source entity set.
bitmap	The handle to a bitmap object.
clear	If set to true the bitmap will be cleared (to white) before it is populated, otherwise the symbol will be drawn over the existing background.

Returns

true if successful, false otherwise (You can check TSLErrorStack for a description of the error).

getSymbolAsEntitySet() [1/2]

TSLEntitySet * TSLAPP6AHelper::getSymbolAsEntitySet

(

const char *

symbol

)

Use this method to convert a valid APP6A string into an entity set, which can be displayed on a map.

Note

symbol: The string to convert to an entity set. ( you can get this string by calling TSLAPP6ASymbol::write() ).

Returns

a pointer to a TSLEntitySet object or NULL on error. The user should assume ownership of the entity set and call 'destroy()' on it after they have finished with it.

(You can check TSLErrorStack for a description of the error if the pointer is NULL).

getSymbolAsEntitySet() [2/2]

TSLEntitySet * TSLAPP6AHelper::getSymbolAsEntitySet

(

const TSLAPP6ASymbol *

symbol

)

Use this method to convert a TSLAPP6ASymbol object into an entity set, which can be displayed on a map.

Parameters

symbol

The symbol to convert into an entity set.

Returns

a pointer to a TSLEntitySet object or NULL on error. The user should assume ownership of the entity set and call 'destroy()' on it after they have finished with it.

(You can check TSLErrorStack for a description of the error if the pointer is NULL).

getSymbolFromID()

bool TSLAPP6AHelper::getSymbolFromID	(	const char *	id,
		TSLAPP6ASymbol &	symbol )

Use this method to construct a symbol from its symbol ID.

Parameters

id	A string containing the id of the symbol required. For example passing "1.x.1.1" would construct the satellite symbol.
symbol	The TSLAPP6ASymbol object to be populated.

Remarks

The following fields are populated in the symbol object

1. key
2. name
3. depth
4. type
5. isFrameOptional

All other fields will remain unchanged.

The current value of the id and key fields within the symbol object passed to this method are ignored.

Returns

True if the symbol id is found and the symbol is populated, or false otherwise.

getSymbolFromSIDC2525B()

bool TSLAPP6AHelper::getSymbolFromSIDC2525B	(	const char *	sidc,
		TSLAPP6ASymbol &	symbol )

getSymbolFromSIDCAPP6A()

bool TSLAPP6AHelper::getSymbolFromSIDCAPP6A	(	const char *	sidc,
		TSLAPP6ASymbol &	symbol )

isAPP6A()

bool TSLAPP6AHelper::isAPP6A

(

const TSLEntitySet *

es

)

Use this method to check is an entity set is a valid APP6A symbol.

Parameters

es	A pointer to the entity set which should be checked.

Returns

true if the symbol is valid, false otherwise.

numOfSymbols()

int TSLAPP6AHelper::numOfSymbols

(

)

Use this method to get the number of symbols in the configuration file.

Returns

An integer value indicating the number of symbols.

operator new() [1/2]

void * TSLAPP6AHelper::operator new

(

size_t

size

)

operator new() [2/2]

void * TSLAPP6AHelper::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

setDefaultConfigPath()

static void TSLAPP6AHelper::setDefaultConfigPath ( const char * path )

static

Use this method to set the default location of the configuration file you wish to use. This can either be the path to a directory, in which case the class will attempt to load the app6aConfig.csv file from that directory, or the full path to the configuration file to use including filename.

When a TSLAPP6AHelper class is constructed it will first check if a path has been passed in the constructor and attempt to load that. However, if no path has been passed, the default config path will be used to locate the symbols.

Parameters

path	The location of the configuration file.

valid()

bool TSLAPP6AHelper::valid

(

)

Use this method to check if the configuration file loaded successfully.

Returns

True if the file loaded okay, false otherwise.