Detailed Description

Specialist user defined geometry entity.

The developer should derive a new class from this class and implement the draw method as a minimum.

The save method should be implemented if you wish to persist your object when save is called on a layer. You will need to provide callbacks for loading (see TSLUserGeometryEntity).

It is suggested that you write out a header that clearly identifies the object type uniquely within your application or company.

It is the developer's responsibility to ensure thread safety.

Public Member Functions
virtual	~TSLClientUserGeometryEntity ()

virtual bool	contains (const TSLEntity *anotherEntity) const

virtual bool	crosses (const TSLEntity *anotherEntity) const

virtual TSLEntitySet *	difference (const TSLEntity *other) const

virtual bool	draw (int uniqueSurfaceID, TSLRenderingInterface *renderingInterface, const TSLEnvelope &extent, TSLRenderLevel renderLevel, double screenResolution)=0

virtual TSLEnvelope	envelope (int uniqueSurfaceID)

virtual bool	equals (const TSLEntity *anotherEntity) const

virtual unsigned int	inMemorySize ()

virtual TSLEntitySet *	intersection (const TSLEntity *anotherEntity) const

virtual bool	intersects (const TSLEntity *anotherEntity) const

virtual bool	overlaps (const TSLEntity *anotherEntity) const

virtual void	releaseResources (int surfaceID)

virtual bool	rotate (double angle, const TSLCoord *origin=NULL)

virtual int	save (TSLofstream &stream)

virtual bool	scale (double scaleOnX, double scaleOnY, const TSLCoord *origin=NULL)

virtual double	squareDistance (const TSLCoord &point, const TSLEnvelope *aperture=NULL, bool useRenderedExtent=true, int drawingSurfaceID=-1) const

virtual double	squareDistance (const TSLEntity *otherEntity) const

virtual bool	touches (const TSLEntity *anotherEntity) const

virtual bool	translate (TSLTMC xoffset, TSLTMC yoffset)

virtual TSLEntitySet *	unionWith (const TSLEntity *anotherEntity) const

virtual bool	valid ()

virtual TSLCoord	adjustedWeightedCentroid ()
	reserved for future use

virtual TSLCoord	centreOfGravity ()
	reserved for future use

Protected Member Functions
	TSLClientUserGeometryEntity ()

Constructor & Destructor Documentation

◆ ~TSLClientUserGeometryEntity()

virtual TSLClientUserGeometryEntity::~TSLClientUserGeometryEntity ( )

virtual

Default destructor for ~TSLClientUserGeometryEntity

◆ TSLClientUserGeometryEntity()

TSLClientUserGeometryEntity::TSLClientUserGeometryEntity ( )

protected

Default constructor for TSLClientUserGeometryEntity

Declared protected to prevent non-derived classes from accessing this class.

Member Function Documentation

◆ adjustedWeightedCentroid()

virtual TSLCoord TSLClientUserGeometryEntity::adjustedWeightedCentroid ( )

virtual

reserved for future use

◆ centreOfGravity()

virtual TSLCoord TSLClientUserGeometryEntity::centreOfGravity ( )

virtual

reserved for future use

◆ contains()

virtual bool TSLClientUserGeometryEntity::contains ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Tests if this entity 'spatially contains' another entity.

The base implementation returns false.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the other entity is contained, false otherwise.

◆ crosses()

virtual bool TSLClientUserGeometryEntity::crosses ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Tests if this entity 'spatially crosses' another entity.

The base implementation returns false.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the entities cross, false otherwise.

◆ difference()

virtual TSLEntitySet * TSLClientUserGeometryEntity::difference ( const TSLEntity * other ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Creates the spatial difference between the two entities.

The base implementation returns NULL.

Parameters

other Another entity to perform test against.

Returns: an entity that represents the difference of the source TSLentity and another TSLEntity. If no geometric difference is possible, then a NULL entity is returned.

◆ draw()

virtual bool TSLClientUserGeometryEntity::draw	(	int	uniqueSurfaceID,
		TSLRenderingInterface *	renderingInterface,
		const TSLEnvelope &	extent,
		TSLRenderLevel	renderLevel,
		double	screenResolution )

pure virtual

The developer needs to implement this method in their derived class.

This method is called to draw the entity.

The user is responsible for setting up the rendering and drawing of the object. MapLink will not set up any rendering or apply any feature rendering to this object.

Parameters

uniqueSurfaceID	A unique surface number. Can be used for caching data as this will be unique to the calling surface.
renderingInterface	Rendering Interface. Allows the developer to draw using the MapLink Rendering Engine.
extent	Display drawing extent only.
renderLevel	The render level that the draw is being called for. The values passed are TSLRenderLevelMinusFive..TSLRenderLevelPlusFive. Most drawing occurs at TSLRenderLevelZero only.
screenResolution	The screen resolution (TMCs per Device Unit)

Returns: true if an object is drawn, false otherwise.

◆ envelope()

virtual TSLEnvelope TSLClientUserGeometryEntity::envelope ( int uniqueSurfaceID )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

It is advised that this method is implemented as the returned envelope is used to decide if to call the drawing method. The default implementation returns a full TMC extent.

Query the minimum bounding box of the entity.

Parameters

uniqueSurfaceID an id for a drawing surface. This is unique to a surface.

Returns: the minimum bounding box of the entity.

◆ equals()

virtual bool TSLClientUserGeometryEntity::equals ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Test for spatial equality with another entity.

The base implementation returns false.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the entities are the same, false otherwise.

◆ inMemorySize()

virtual unsigned int TSLClientUserGeometryEntity::inMemorySize ( )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns the memory size for this class only.

Returns: an estimate of the in memory size in bytes for the class.

◆ intersection()

virtual TSLEntitySet * TSLClientUserGeometryEntity::intersection ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Creates a spatial intersection between the two entities.

The base implementation returns NULL.

Parameters

anotherEntity Another entity to perform test against.

Returns: An entity that represents the intersection of the source TSLEntity with another TSLEntity.

◆ intersects()

virtual bool TSLClientUserGeometryEntity::intersects ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Test for spatial intersection between the two entities.

The base implementation returns false.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the entities intersect, false otherwise.

◆ overlaps()

virtual bool TSLClientUserGeometryEntity::overlaps ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Tests if this entity 'spatially overlaps' another entity.

The base implementation returns false.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the entities overlap, false otherwise.

◆ releaseResources()

virtual void TSLClientUserGeometryEntity::releaseResources ( int surfaceID )

virtual

This method is called when the Drawing Surface invalidates its native drawing resources.

The user will need to release any surface specific resources.

The use of this method is very dependent upon the Drawing Surface technology.

Parameters

surfaceID A unique surface number.

◆ rotate()

virtual bool TSLClientUserGeometryEntity::rotate	(	double	angle,
		const TSLCoord *	origin = NULL )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns false.

Rotates the entity.

Rotates the TSLEntity anti-clockwise by angle, about specified origin. Uses centroid as the reference of the rotation if origin is NULL.

Angle is given in radians.

For entities that have an internal rotation, such as text or symbols, this adds to the rotation angle, and possibly changes the position of the entity.

For entities that contain a CoordSet, the coordinates are changed.

Parameters

angle	Angle to rotate by, in radians, anti-clockwise +ve.
origin	Point to rotate about. NULL origin uses centroid.

Returns: true if the rotate occurred, false if the rotate could not be applied. If the rotate can not be applied then the entity is not changed. The only reason for the rotate not being applied is if an attempt is made to rotate the entity fully or partially outside TMC space.

◆ save()

virtual int TSLClientUserGeometryEntity::save ( TSLofstream & stream )

virtual

This function is called to save the User Geometry object.

The save method should be implemented if you wish to persist your object when save is called on a layer.

It is suggested that you write out a header that clearly identifies the object type uniquely within your application or company. The value returned from this method is used when re-creating the object.

Notes:

The returned value is passed to any registered callback functions to identify the geometry object type saved. It is therefore suggested that you publish and track the use of these IDs in your application or SDK (OEM users) as the values must be unique.
The value returned will be passed to the load callback when the entity is being loaded.

Parameters

stream The output file stream to store the User Geometry object data to.

Returns: a positive integer value that is unique to your application or company for this object type. Negative numbers are reserved for internal use only.

◆ scale()

virtual bool TSLClientUserGeometryEntity::scale	(	double	scaleOnX,
		double	scaleOnY,
		const TSLCoord *	origin = NULL )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

Scales this entity, equally in both directions.

The base implementation returns false.

Parameters

scaleOnX,scaleOnY	Scaling factors to apply in the X and Y axes. 0 is invalid.
origin	Origin to scale about. If origin is NULL, the origin of the scale is the centroid of the TSLEntity.

Returns: true if the scale occurred, false if the scale could not be applied. If the scale can not be applied then the entity is not changed. The possible reasons for the scale not being applied are if an attempt is made to scale the entity fully or partially outside TMC space or scaling the entity too small.

◆ squareDistance() [1/2]

virtual double TSLClientUserGeometryEntity::squareDistance	(	const TSLCoord &	point,
		const TSLEnvelope *	aperture = NULL,
		bool	useRenderedExtent = true,
		int	drawingSurfaceID = -1 ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

This method calculates the shortest square distance between an entity and a point.

Depending upon the reason for this method being invoked, an aperture parameter maybe provided to reduce the calculations required, so that anything that falls outside the aperture envelope can be disregarded. If the entity does fall completely outside the aperture, DBL_MAX should be returned.

As entities may have a different extent when rendered, for instance due to scale based rendering attributes, a flag is provided to describe whether the rendered extent should be used to make this calculation. The drawing surface id of the drawing surface upon which the entity's rendered extent is take from is also provided.

The base implementation returns -1.

Parameters

point	The point to which the square distance should be calculated.
aperture	The aperture around the point, usually an equal distance in all directions, that may optionally be provided to reduce calculations.
useRenderedExtent	Flag to indicate whether the rendered extent of the entity should be used.
drawingSurfaceID	The ID the drawing surface that drew the entity. This is only relevant when the useRenderedExtent is set to true.

Returns: the shortest square distance to the point, or -1 to indicate that an error occurred.

◆ squareDistance() [2/2]

virtual double TSLClientUserGeometryEntity::squareDistance ( const TSLEntity * otherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

This method calculates the shortest square distance between entities.

The otherEntity may be a group or series of groups. In this case the square distance returned is to the closest non-group entity.

The base implementation returns -1.

Parameters

otherEntity entity to query the shortest distance too.

Returns: the shortest square distance to the otherEntity. Return -1 to indicate an error.

◆ touches()

virtual bool TSLClientUserGeometryEntity::touches ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns false.

Tests if this entity 'spatially touches' another entity.

Parameters

anotherEntity Another entity to perform test against.

Returns: true if the entities touch, false otherwise.

◆ translate()

virtual bool TSLClientUserGeometryEntity::translate	(	TSLTMC	xoffset,
		TSLTMC	yoffset )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns false.

Translates this entity by delta.

Parameters

xoffset	delta applied to X coordinates.
yoffset	delta applied to Y coordinates.

Returns: true if the translate occurred, false if the translate could not be applied. If the translate can not be applied then the entity is not changed. The only reason for the translate not being applied is if an attempt is made to translate the entity fully or partially outside TMC space.

◆ unionWith()

virtual TSLEntitySet * TSLClientUserGeometryEntity::unionWith ( const TSLEntity * anotherEntity ) const

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns NULL.

Creates a spatial union between the two entities.

Parameters

anotherEntity Another entity to perform test against.

Returns: an entity that represents the union of the source TSLEntity with another TSLEntity. If no geometric union is possible, then a group containing the entities is returned.

◆ valid()

virtual bool TSLClientUserGeometryEntity::valid ( )

virtual

The developer needs to implement this method in their derived class if the functionality is required.

The base implementation returns true.

Returns: true if valid false otherwise.

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ ~TSLClientUserGeometryEntity()

◆ TSLClientUserGeometryEntity()

Member Function Documentation

◆ adjustedWeightedCentroid()

◆ centreOfGravity()

◆ contains()

◆ crosses()

◆ difference()

◆ draw()

◆ envelope()

◆ equals()

◆ inMemorySize()

◆ intersection()

◆ intersects()

◆ overlaps()

◆ releaseResources()

◆ rotate()

◆ save()

◆ scale()

◆ squareDistance() [1/2]

◆ squareDistance() [2/2]

◆ touches()

◆ translate()

◆ unionWith()

◆ valid()