TSLTrackBase Class Referenceabstract
Inheritance diagram for TSLTrackBase:

Detailed Description

TSLTrackBase class for use with the Track Display Manager This class defines a common set of attributes and functionality for TSLTrack and TSLTrackGroup

This class is reference counted internally to allow objects to be shared within the track manager SDK

  • Ownership of this object will never be transferred from the application to MapLink
  • The application must call release() in order to relinquish its ownership, even if the object has been passed to another

Public Types

enum  TrackType { Track , TrackGroup }
 
enum  AggregationState { AggregationDisabled , AggregationEnabled , AggregationDisabledByGraphic }
 
typedef uint32_t TrackID
 

Public Member Functions

virtual TSLTrackBase::TrackType type () const =0
 
void release ()
 
virtual TSLTrackBaseclone () const =0
 
AggregationState aggregationState () const
 
void allowAggregation (bool allow)
 
void hierarchyLevel (uint32_t level)
 
uint32_t hierarchyLevel () const
 
TSLTrackBase::TrackID trackNumber () const
 
void aggregator (TSLTrackAggregator *aggregator)
 
TSLTrackAggregatoraggregator () const
 
void hierarchyAggregator (TSLTrackAggregatorEchelon *aggregator)
 
TSLTrackAggregatorEchelonhierarchyAggregator () const
 
double latitude () const
 
double currentLatitude () const
 
double longitude () const
 
double currentLongitude () const
 
double velocity () const
 
double currentVelocity () const
 
double heading () const
 
double currentHeading () const
 
double altitude () const
 
double currentAltitude () const
 
bool addAttribute (const char *name, const char *key, bool staticAttribute)
 
bool setAttributeValue (const char *name, const char *value)
 
const char * getAttributeName (const char *key) const
 
const char * getAttributeKey (const char *name) const
 
const char * getAttributeValue (const char *name) const
 
const char * getCurrentAttributeValue (const char *name) const
 
bool queryAttribute (unsigned int index, TSLSimpleString *name, TSLSimpleString *key, TSLSimpleString *value) const
 
unsigned int numAttributes () const
 
bool deleteAttribute (const char *name)
 
void deleteAttributes ()
 Delete all attributes. More...
 
bool addSymbol (TSLTrackSymbol *symbol)
 
void clearHistoryPointColour ()
 Clear the override colour for history points/symbols. More...
 
void historyPointColour (const TSLRGBA &colour)
 
bool updateSymbol (uint32_t index, TSLTrackSymbol *symbol)
 
void removeSymbol (uint32_t index)
 
uint32_t numberOfSymbols () const
 
TSLTrackSymbolsymbolAt (uint32_t index) const
 
void visible (int drawingSurfaceID, bool visibility)
 
void select (int drawingSurfaceID, bool selected)
 
bool selected (int drawingSurfaceID)
 
void velocity (double velocity)
 
void heading (double heading)
 
void altitude (double altitude)
 
void trackName (const char *name)
 
void userID (uint32_t id)
 
uint32_t userID () const
 
const char * trackName () const
 
void historyPointsVisible (int drawingSurfaceID, bool visibility)
 
void featureID (TSLFeatureID featureID)
 
TSLFeatureID featureID () const
 
bool featureName (const char *featureName)
 
void parentGroup (TSLTrackBase *parentGroup)
 
TSLTrackBaseparentGroup ()
 
void * p () const
 

Protected Member Functions

 TSLTrackBase ()
 
 TSLTrackBase (const TSLTrackBase &other)
 
virtual ~TSLTrackBase ()
 
void operator delete (void *ptr)
 

Member Typedef Documentation

◆ TrackID

typedef uint32_t TSLTrackBase::TrackID

A numeric identifier for a Track These IDs are unique within a TSLTrackDisplayManager

Member Enumeration Documentation

◆ AggregationState

Enumerator
AggregationDisabled 

This track is not aggregated and will be visible Either an aggregator hasn't been assigned to the track or the user has called allowAggregation( false ).

AggregationEnabled 

This track is aggregated It will only be visible within its aggregation limits

AggregationDisabledByGraphic 

This track is not aggregated because it is used as a control point for a track graphic

Aggregation will be reset to the application's setting once the graphic has been removed

◆ TrackType

Enumerator
Track 
TrackGroup 

Constructor & Destructor Documentation

◆ TSLTrackBase() [1/2]

TSLTrackBase::TSLTrackBase ( )
protected

◆ TSLTrackBase() [2/2]

TSLTrackBase::TSLTrackBase ( const TSLTrackBase other)
protected

◆ ~TSLTrackBase()

virtual TSLTrackBase::~TSLTrackBase ( )
protectedvirtual

Member Function Documentation

◆ addAttribute()

bool TSLTrackBase::addAttribute ( const char *  name,
const char *  key,
bool  staticAttribute 
)

Add an attribute to the track to be used in its texts and symbols.

To visualise the attribute [for example with key: AK]:

  1. The track symbol should contain a TSLText with text="AnyText__AK" or contain a TSLSymbol with "__AK".
  2. The method 'setAttributeValue' has to be called to set the value of the attribute to be used in visualisation.

Reserved Attribute keys

  • 'TN' to represent Track Name
  • 'TH' to represent Track Heading
  • 'TA' to represent Track Altitude
  • 'TV' to represent Track Velocity
  • 'NC' to represent TrackGroup Number Of Children
  • 'NT' to represent TrackGroup Number Of Tracks

This method will fail if:

  1. the attribute name already exists.
  2. the key is null.
  3. the key is not 2 characters length.
  4. the key is taken by other attributes.
  5. the key is taken by one of the reserved attributes.
Parameters
nameName of the attribute to set.
keyThis should be in the form of the 2 character key.
staticAttributeFlag to be set to treat the attribute as static for optimisation.
Returns
true if successful. false otherwise

◆ addSymbol()

bool TSLTrackBase::addSymbol ( TSLTrackSymbol symbol)

Add a track visualisation defined by a TSLTrackSymbol

The symbol should have the desired display resolution set via the TSLTrackSymbol::maximumResolution method prior to calling this method. Each symbol added in this fashion should have a unique maximum resolution set to provide a different visualisation at multiple resolutions.

The Symbol must be a TSLTrackPointSymbol.

The track will take a reference to the TSLTrackSymbol, which may be shared between multiple tracks. The application may continue to use the symbol for as long as it holds a reference.

Parameters
symbolThe symbol to add
Returns
true if the symbol was added, false if an invalid symbol was provided.

◆ aggregationState()

AggregationState TSLTrackBase::aggregationState ( ) const

Getter only for the aggregation state The only way the user can affect this is to assign an aggregator to the track

  • If the track is reference by a graphic the getter must return AggregationByGraphic
  • If the track has an aggregator assigned return Aggregation enabled
  • If the track doesn't have an aggregator assigned return Aggregation disabled

◆ aggregator() [1/2]

TSLTrackAggregator * TSLTrackBase::aggregator ( ) const

◆ aggregator() [2/2]

void TSLTrackBase::aggregator ( TSLTrackAggregator aggregator)

Setter/getter for the aggregator

  • By default an aggregator isn't assigned to a track
  • If set the track may be aggregated when drawn, based on whatever the aggregator's rules are
  • Setting/clearing the aggregator on a track will trigger a change in the aggregationState of the track, unless it is referenced by a track graphic
  • A track may have two aggregators assigned at once, one through this function and one through the hierarchyAggregator function.
  • If there are 2 children in a track group they may have different aggregators assigned to them. This is because aggregation will be performed bottom-up when rendering. This isn't a very likely scenario however shouldn't cause any problems/additional effort if we provide this possibility.

◆ allowAggregation()

void TSLTrackBase::allowAggregation ( bool  allow)

Setter to allow the user to prevent aggregation of this track or to allow aggregation to be performed by the aggregator

Regardless of what the user passes here tracks will never be aggregated if they are referenced by a track graphic

There is intentionally not a getter here. Users must call aggregationState() which will say whether aggregation is enabled or not, and the reason why it is disabled if applicable.

◆ altitude() [1/2]

double TSLTrackBase::altitude ( ) const

Query the altitude of this track at the display time of the TSLTrackDisplayManager.

Returns
The altitude of this track.

◆ altitude() [2/2]

void TSLTrackBase::altitude ( double  altitude)

Set the altitude of this track at the current time.

Parameters
altitudeThe new altitude.

◆ clearHistoryPointColour()

void TSLTrackBase::clearHistoryPointColour ( )

Clear the override colour for history points/symbols.

◆ clone()

virtual TSLTrackBase * TSLTrackBase::clone ( ) const
pure virtual

Create a clone of this TSLTrack.

The cloned object will not be attached to any TSLTrackDisplayManager Historic data from the source track and referenced symbols will be copied, however the per-surface state and history points will not.

If a clone needs to be created while preserving this data, the TSLTrackDisplayManager::cloneTrackInto method should be used.

Returns
A clone of this Track.

Implemented in TSLTrack, and TSLTrackGroup.

◆ currentAltitude()

double TSLTrackBase::currentAltitude ( ) const

Query the altitude of this track at the current time.

Returns
The altitude of this track.

◆ currentHeading()

double TSLTrackBase::currentHeading ( ) const

Query the heading of this track, in degrees at the current time.

Returns
The heading of this track.

◆ currentLatitude()

double TSLTrackBase::currentLatitude ( ) const

Query the latitude of the track at the current time.

Returns
The current latitude of the track in WGS84.

◆ currentLongitude()

double TSLTrackBase::currentLongitude ( ) const

Query the longitude of the track at the current time.

Returns
The current longitude of the track in WGS84.

◆ currentVelocity()

double TSLTrackBase::currentVelocity ( ) const

Query the velocity of this track at the current time.

Returns
The velocity of this track.

◆ deleteAttribute()

bool TSLTrackBase::deleteAttribute ( const char *  name)

Delete an attribute.

If the input name is a 2-characters name, it will search for the attribute with the same key. If the input name is not found as a key or it is more that 2 characters, it will search for the attribute with the same name.

Parameters
nameName of the attribute to clear.

◆ deleteAttributes()

void TSLTrackBase::deleteAttributes ( )

Delete all attributes.

◆ featureID() [1/2]

TSLFeatureID TSLTrackBase::featureID ( ) const
Returns
Returns the current feature ID for this track.

◆ featureID() [2/2]

void TSLTrackBase::featureID ( TSLFeatureID  featureID)

Sets the feature type for the track by ID. Features must first be created on the data layer for the TSLTrackDisplayManager that this track is in.

Setting a feature type on the track allows it to be decluttered.

Parameters
featureIDThe ID of the feature type for this track.

◆ featureName()

bool TSLTrackBase::featureName ( const char *  featureName)

Sets the feature type for the track by name. Features must first be created on the data layer for the TSLTrackDisplayManager that this track is in.

Parameters
featureNameThe name of the feature type for this track.
Returns
true if the given feature name corresponds to a feature for the TSLTrackDisplayManager's data layer and the track's feature type is updated, false otherwise.

◆ getAttributeKey()

const char * TSLTrackBase::getAttributeKey ( const char *  name) const

Query the value of an attribute's 2 characters key.

Parameters
nameName of the attribute to query.
Returns
The attribute key or NULL if the attribute isn't set.

◆ getAttributeName()

const char * TSLTrackBase::getAttributeName ( const char *  key) const

Query the name of the attribute.

Parameters
theattribute's 2 characters key.
Returns
The attribute name or NULL if the attribute isn't set.

◆ getAttributeValue()

const char * TSLTrackBase::getAttributeValue ( const char *  name) const

Query the value of an attribute at the 'display time'.

If the input name is a 2-characters name, it will search for the attribute with the same key. If the input name is not found as a key or it is more that 2 characters, it will search for the attribute with the same name.

Parameters
nameName of the attribute to query.
Returns
The value of the attribute or NULL if the attribute isn't set.

◆ getCurrentAttributeValue()

const char * TSLTrackBase::getCurrentAttributeValue ( const char *  name) const

Query the value of an attribute at the 'current latest time'.

If the input name is a 2-characters name, it will search for the attribute with the same key. If the input name is not found as a key or it is more that 2 characters, it will search for the attribute with the same name.

Parameters
nameName of the attribute to query.
Returns
The current value of the attribute or NULL if the attribute isn't set.

◆ heading() [1/2]

double TSLTrackBase::heading ( ) const

Query the heading of this track, in degrees at the display time of the TSLTrackDisplayManager.

Returns
The heading of this track.

◆ heading() [2/2]

void TSLTrackBase::heading ( double  heading)

Set the heading of this track, in degrees at the current time.

Parameters
headingThe new heading.

◆ hierarchyAggregator() [1/2]

TSLTrackAggregatorEchelon * TSLTrackBase::hierarchyAggregator ( ) const

◆ hierarchyAggregator() [2/2]

void TSLTrackBase::hierarchyAggregator ( TSLTrackAggregatorEchelon aggregator)

Setter/getter for the hierarchy aggregator This is intended to be for Echelon type aggregators where it is required that the aggregator be processed first and the output passed to the other aggregator (if set).

  • By default an aggregator isn't assigned to a track
  • If set the track may be aggregated when drawn, based on whatever the aggregator's rules are
  • Setting/clearing the aggregator on a track will trigger a change in the aggregationState of the track, unless it is referenced by a track graphic
  • A track may have two aggregators assigned at once, one through this function and one through the Aggregator function.
  • If there are 2 children in a track group they may have different aggregators assigned to them. This is because aggregation will be performed bottom-up when rendering. This isn't a very likely scenario however shouldn't cause any problems/additional effort if we provide this possibility.

◆ hierarchyLevel() [1/2]

uint32_t TSLTrackBase::hierarchyLevel ( ) const

◆ hierarchyLevel() [2/2]

void TSLTrackBase::hierarchyLevel ( uint32_t  level)

Setters/getter for the hierarchy level This is a numeric index which specifies which aggregation level the track is considered part of

  • The default value for this level should be automatically calculated based on the position in the tree
  • For all leaf nodes the value would be 0
  • For any non-leaf node the value would be the number of steps down the tree needed to reach a leaf node
  • This should be set when the track is added to it's parent object, but only if the user has not already set this
  • An additional flag will be needed internally to track whether the user has overridden this level

While the default structure would be to have 0 at the leaves and increasing further up the tree there is no specific order to this value. This will allow users to pass in enums such as the TSLAPP6ASymbol::UnitSize directly to use as the hierarchy level/echelon number

This is just a stored attribute here and will not have any direct effect on the track itself This will however then be used by the aggregator in order to determine what the rules are/which parent should be drawn if any

This disconnect is intentional such that:

  • The track tree/hierarchy can be used to model the real-world relationship between the tracks (squaddie->squad->platoon etc)
  • The aggregator can perform implementation-specific logic without being bound to the echelon/hierarchy if needs be

◆ historyPointColour()

void TSLTrackBase::historyPointColour ( const TSLRGBA colour)

Set the override colour for the history points/symbols.

If this is not set:

If this is set:

  • History points will be drawn as this colour.
  • History symbols will be updated to use this colour, instead of the colour set on the TSLTrackHistorySymbol object.

This colour may be cleared using the clearHistoryPointColour method.

Parameters
colourThe colour to use when drawing history points/symbol.

◆ historyPointsVisible()

void TSLTrackBase::historyPointsVisible ( int  drawingSurfaceID,
bool  visibility 
)

Set the visibility of history points, for a given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
visibilityThe visibility of history points on the drawing surface.

◆ latitude()

double TSLTrackBase::latitude ( ) const

Query the latitude of the track at the display time of the TSLTrackDisplayManager.

Returns
The latitude of the track in WGS84.

◆ longitude()

double TSLTrackBase::longitude ( ) const

Query the longitude of the track at the display time of the TSLTrackDisplayManager.

Returns
The longitude of the track in WGS84.

◆ numAttributes()

unsigned int TSLTrackBase::numAttributes ( ) const

Query the number of attributes.

Returns
The number of attributes assigned to this track.

◆ numberOfSymbols()

uint32_t TSLTrackBase::numberOfSymbols ( ) const

Query the number of symbols used by this track.

Returns
The number of symbols.

◆ operator delete()

void TSLTrackBase::operator delete ( void *  ptr)
protected

◆ p()

void * TSLTrackBase::p ( ) const

◆ parentGroup() [1/2]

TSLTrackBase * TSLTrackBase::parentGroup ( )
Returns
Returns the current parent TrackGroup for this track.

◆ parentGroup() [2/2]

void TSLTrackBase::parentGroup ( TSLTrackBase parentGroup)

Sets the parent TrackGroup for this track.

This is intended to be used to facilitate the setting up of a hierarchy of tracks and trackgroups. For example, when an Echelon structure is desired to be used with Aggregation.

Parameters
parentGroupThe parent TrackGroup object for this track.

◆ queryAttribute()

bool TSLTrackBase::queryAttribute ( unsigned int  index,
TSLSimpleString name,
TSLSimpleString key,
TSLSimpleString value 
) const

Query an attribute by index at the 'display time'.

Parameters
indexThe index of the attribute to query.
nameWill be set to the name of the attribute.
keyWill be set to the value of the attribute's 2 characters key.
valueWill be set to the value of the attribute at the 'display time'.
Returns
true if the name and value were set, false otherwise.

◆ release()

void TSLTrackBase::release ( )

Release ownership of this object

The object will be deleted once the application has called release and any references held by MapLink have been released

◆ removeSymbol()

void TSLTrackBase::removeSymbol ( uint32_t  index)

Remove a symbol from the track.

Parameters
indexThe symbol to remove.

◆ select()

void TSLTrackBase::select ( int  drawingSurfaceID,
bool  selected 
)

Set the selection marker status of this track, for a given drawing surface.

Parameters
drawingSurfaceIDThe drawing surface to set the visibility for.
selectedThe selection marker state.

◆ selected()

bool TSLTrackBase::selected ( int  drawingSurfaceID)

Queries the selection status of this track, for a given drawing surface.

Parameters
drawingSurfaceIDThe drawing surface to query the select status for.
Returns
The selected status the track for the specified drawing surface.

◆ setAttributeValue()

bool TSLTrackBase::setAttributeValue ( const char *  name,
const char *  value 
)

Update the value of an attribute at the 'current time' [cannot set it in the past].

If the input name is a 2-characters name, it will search for the attribute with the same key. If the input name is not found as a key or it is more that 2 characters, it will search for the attribute with the same name.

Parameters
nameName of the attribute to set.
valueValue of the attribute.
Returns
true if successful. False if the attribute name does not exist.

◆ symbolAt()

TSLTrackSymbol * TSLTrackBase::symbolAt ( uint32_t  index) const

Query a track visualisation

Symbols are returned in level of detail order, which may be different to the order the symbols were originally added to the track in.

The returned symbol may be modified by the application however the application must not call release on the returned pointer

Parameters
indexThe symbol to query
Returns
The requested symbol, or NULL if an invalid index was provided.

◆ trackName() [1/2]

const char * TSLTrackBase::trackName ( ) const

Query the displayed name of this track.

Returns
The name of this track.

◆ trackName() [2/2]

void TSLTrackBase::trackName ( const char *  name)

Set the displayed name of this track.

The parameters for displaying the track name are defined by the currently displayed TSLTrackPointSymbol object.

Parameters
nameThe name of this track.

◆ trackNumber()

TSLTrackBase::TrackID TSLTrackBase::trackNumber ( ) const

Query the track number allocated for this track.

Returns
The track number of this track.

◆ type()

virtual TSLTrackBase::TrackType TSLTrackBase::type ( ) const
pure virtual

Implemented in TSLTrack, and TSLTrackGroup.

◆ updateSymbol()

bool TSLTrackBase::updateSymbol ( uint32_t  index,
TSLTrackSymbol symbol 
)

Update a track visualisation defined by a TSLTrackSymbol

The provided Symbol must be a TSLTrackPointSymbol

The track will take a reference to the TSLTrackSymbol, which may be shared between multiple tracks. The application may continue to use the symbol for as long as it holds a reference.

Parameters
indexThe symbol to update.
symbolThe new parameters for the symbol.
Returns
true if the symbol was updated, false if an invalid symbol was provided.

◆ userID() [1/2]

uint32_t TSLTrackBase::userID ( ) const

Query the user ID of this track.

Returns
The user ID of this Track, or 0 if one has not been assigned.

◆ userID() [2/2]

void TSLTrackBase::userID ( uint32_t  id)

Set the user ID of this track.

This ID is provided for use by an application, and is unrelated to the TrackID used by the TSLTrackDisplayManager.

Parameters
idThe user ID to assign to this Track.

◆ velocity() [1/2]

double TSLTrackBase::velocity ( ) const

Query the velocity of this track at the display time of the TSLTrackDisplayManager.

Returns
The velocity of this track.

◆ velocity() [2/2]

void TSLTrackBase::velocity ( double  velocity)

Set the velocity of this track at the current time.

Parameters
velocityThe new velocity.

◆ visible()

void TSLTrackBase::visible ( int  drawingSurfaceID,
bool  visibility 
)

Set the visibility of the track, for a given drawing surface.

Parameters
drawingSurfaceIDThe drawing surface to set the visibility for.
visibilityThe new visibility value.