Inheritance diagram for TSLTrackGraphicRuler:

Detailed Description

This class provides a track graphic which displays a ruler within the TSLTrackDisplayManager

The ruler will be displayed as a line, with optional ticks at regular intervals A symbol will be displayed at each of the control points. This may be any symbol provided as part of MapLink, or a user-defined symbol added to config/symbols/tslsymbolsuser.dat

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	UnitOfMeasure { Metres , KiloMetres , Feet , Yards , Miles , NauticalMiles , CustomDistance }
	Specifies the unit of measure used by the ruler. More...

enum	UnitOfAngularMeasure { Degrees , Mils , CustomBearing }

enum	LabelDisplayMode { LabelRelativeToRulerStart , LabelRelativeToSegmentStart , LabelCumulative }
	Defines the types of labels which can be displayed at each point. More...

Public Types inherited from TSLTrackGraphic
enum	ControlPointType { LatLonControlPoint , TrackControlPoint }
	The control point types supported by track graphics. More...

enum	GraphicType { TrackGraphicLink , TrackGraphicArrow , TrackGraphicRuler }
	The types of graphic provided by the MapLink Track Manager SDK. More...

Public Member Functions
void	displaySymbols (bool display)

bool	displaySymbols () const

void	displayDistanceLabel (TSLTrackGraphicRuler::LabelDisplayMode mode, bool display)

bool	displayDistanceLabel (TSLTrackGraphicRuler::LabelDisplayMode mode) const

void	distanceLabelUnitOfMeasure (TSLTrackGraphicRuler::UnitOfMeasure uom)

TSLTrackGraphicRuler::UnitOfMeasure	distanceLabelUnitOfMeasure () const

void	displayBearingLabel (TSLTrackGraphicRuler::LabelDisplayMode mode, bool display)

bool	displayBearingLabel (TSLTrackGraphicRuler::LabelDisplayMode mode) const

void	bearingLabelUnitOfMeasure (TSLTrackGraphicRuler::UnitOfAngularMeasure uom)

TSLTrackGraphicRuler::UnitOfAngularMeasure	bearingLabelUnitOfMeasure () const

void	bearingLabelFactor (double factor)

void	distanceLabelFactor (double factor)

double	bearingLabelFactor () const

double	distanceLabelFactor () const

void	distanceLabelFormat (TSLTrackGraphicRuler::LabelDisplayMode mode, const char *formatString)

const char *	distanceLabelFormat (TSLTrackGraphicRuler::LabelDisplayMode mode) const

void	bearingLabelFormat (TSLTrackGraphicRuler::LabelDisplayMode mode, const char *formatString)

const char *	bearingLabelFormat (TSLTrackGraphicRuler::LabelDisplayMode mode) const

void	displayTicks (bool display)

bool	displayTicks () const

void	tickLength (double length, TSLDimensionUnits units)

double	tickLength () const

TSLDimensionUnits	tickLengthUnits () const

void	tickDistanceDU (TSLDeviceUnits distanceDU)

TSLDeviceUnits	tickDistanceDU () const

void	tickDistance (double distance)

double	tickDistance () const

void	tickDistanceRound (bool round)

bool	tickDistanceRound () const

void	tickDistanceUnitOfMeasure (TSLTrackGraphicRuler::UnitOfMeasure uom)

TSLTrackGraphicRuler::UnitOfMeasure	tickDistanceUnitOfMeasure () const

const TSLRenderingAttributes &	rendering () const

void	rendering (const TSLRenderingAttributes &attribs)

TSLSimpleString	createTextLabel (uint32_t controlPoint, double lat, double lon) const

Public Member Functions inherited from TSLTrackGraphic
TSLTrackGraphic::GraphicType	type () const

void	release ()

void	featureID (TSLFeatureID featureID)

TSLFeatureID	featureID () const

bool	featureName (const char *featureName)

void	userID (uint32_t id)

uint32_t	userID () const

TSLTrack::TrackID	graphicID () const

bool	addControlPoint (double lat, double lon)

bool	addControlPoint (TSLTrack *track)

bool	getControlPointLocation (uint32_t index, double &lat, double &lon) const

TSLTrack *	getControlPointTrack (uint32_t index) const

TSLTrackGraphic::ControlPointType	controlPointType (uint32_t index) const

bool	removeControlPoint (uint32_t index)

uint32_t	numControlPoints () const

bool	insertControlPoint (uint32_t index, double lat, double lon)

bool	insertControlPoint (uint32_t index, TSLTrack *track)

bool	moveControlPoint (uint32_t index, double lat, double lon)

Static Public Member Functions
static TSLTrackGraphicRuler *	create ()

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

	TSLTrackGraphic (const TSLTrackGraphic &other)

virtual	~TSLTrackGraphic ()

void	operator delete (void *ptr)

Member Enumeration Documentation

◆ LabelDisplayMode

enum TSLTrackGraphicRuler::LabelDisplayMode

Defines the types of labels which can be displayed at each point.

Enumerator

LabelRelativeToRulerStart

The label will be displayed, calculated relative to the start point of the ruler.

Distance labels will display the distance between the first point of the ruler and the position of the label. This will be a straight line between these 2 points and will ignore all previous control points of the ruler.
Bearing labels will display the bearing between the first point of the ruler and the position of the label.

LabelRelativeToSegmentStart

The label will be displayed, calculated relative to the previous control point/The start of the ruler segment.

Distance labels will display the distance between the start of the segment and the position of the label.
Bearing labels will display the bearing between the start of the segment and the position of the label.

LabelCumulative

The label will be displayed, calculated as a cumulative value along the ruler.

Distance labels will display the cumulative distance along the ruler.
Bearing labels cannot be calculated as a cumulative value. If this value is set the bearing label will not be displayed.

◆ UnitOfAngularMeasure

enum TSLTrackGraphicRuler::UnitOfAngularMeasure

Enumerator
Degrees	Bearing labels will be displayed in Degrees.
Mils	Bearing labels will be displayed in NATO Mils.
CustomBearing	Can have a multiplication factor applied to the displayed bearing label value. Using the bearingLabelFormat function is required when using this enumeration.

◆ UnitOfMeasure

enum TSLTrackGraphicRuler::UnitOfMeasure

Specifies the unit of measure used by the ruler.

Enumerator
Metres	Distance labels will be displayed in Metres.
KiloMetres	Distance labels will be displayed in Kilometres.
Feet	Distance labels will be displayed in feet.
Yards	Distance labels will be displayed in Yards.
Miles	Distance labels will be displayed in Miles.
NauticalMiles	Distance labels will be displayed in Nautical Miles.
CustomDistance	Can have a multiplication factor applied to the displayed distance label value Using the distanceLabelFormat function is required when using this enumeration.

Member Function Documentation

◆ bearingLabelFactor() [1/2]

double TSLTrackGraphicRuler::bearingLabelFactor ( ) const

Gets the multiplication factor value that is used to calculate the angular units. The factor is only used if the UnitOfAngularMeasure::CustomBearing value is set.

Returns: Currently set multiplication factor which will be applied to a 'CustomBearing' Unit

◆ bearingLabelFactor() [2/2]

void TSLTrackGraphicRuler::bearingLabelFactor ( double factor )

Sets the multiplication factor value that is used to calculate the angular units. The factor is only used if the UnitOfAngularMeasure::CustomBearing value is set. The factor would be applied to a value in degrees in the range 0 - 360.

Default value is 1.0

Parameters

factor Multiplication factor

◆ bearingLabelFormat() [1/2]

const char * TSLTrackGraphicRuler::bearingLabelFormat ( TSLTrackGraphicRuler::LabelDisplayMode mode ) const

Get the formatting for the displayed bearing label.

Parameters

mode	The Label Display mode that the format string will affect

Returns: The 'printf' style format string code set by the user. Default value is: f

◆ bearingLabelFormat() [2/2]

void TSLTrackGraphicRuler::bearingLabelFormat	(	TSLTrackGraphicRuler::LabelDisplayMode	mode,
		const char *	formatString )

Set the formatting for the displayed bearing label.

This function expects a string that is compliant with the C/C++ printf formatting syntax. Passing null or an empty string will revert the formatting to display the default bearing formatting. If the TSLTrackGraphicRuler::UnitOfMeasure used is a standard UoM, reverting the formatting will ensure the bearing label has the associated suffix when it is displayed.

Examples:

"%0.4f" - 42.0000
"%0.1f degrees" - 42.0 degrees
"%e degrees" - Bearing in degrees, using scientific notation

Parameters

mode	The Label Display mode that the format string will affect
formatString	The sequence used to format the displayed distance label value

◆ bearingLabelUnitOfMeasure() [1/2]

TSLTrackGraphicRuler::UnitOfAngularMeasure TSLTrackGraphicRuler::bearingLabelUnitOfMeasure ( ) const

Get the unit of measure for bearing labels

Returns: The unit of measure for bearing labels

◆ bearingLabelUnitOfMeasure() [2/2]

void TSLTrackGraphicRuler::bearingLabelUnitOfMeasure ( TSLTrackGraphicRuler::UnitOfAngularMeasure uom )

Set the unit of measure for bearing labels

The unit of measure determines which units the bearing labels are displayed in, and whether fixed/automatic scaling between multiple units are used. The default unit of measure is TSLTrackGraphicRuler::Degrees

Parameters

uom	The unit of measure for bearing labels

◆ create()

static TSLTrackGraphicRuler * TSLTrackGraphicRuler::create ( )

static

Create a ruler graphic

After calling this method the application must call addControlPoint at least 2 times in order to define the points of the ruler

After calling this method the application may set the graphic's rendering attributes via the rendering method

◆ createTextLabel()

TSLSimpleString TSLTrackGraphicRuler::createTextLabel	(	uint32_t	controlPoint,
		double	lat,
		double	lon ) const

Create a text label

This method will calculate the distance between the provided control point and lat/lon position, and construct a TSLSimpleString which contains a readout of this calculation.

The contents of the text label will use the configuration of this object and will be constructed in the same way as all other ruler labels.

Calling this method will not affect the configuration/visualisation of the ruler graphic.

Parameters

controlPoint	The text label will be calculated in relation to this control point
lat	The latitude to calculate distance/bearing to (WGS84)
lon	The longitude to calculate distance/bearing to (WGS84)

Returns: A string containing the distance/bearing readout, configured as per the ruler labels

◆ displayBearingLabel() [1/2]

bool TSLTrackGraphicRuler::displayBearingLabel ( TSLTrackGraphicRuler::LabelDisplayMode mode ) const

Get whether a type of bearing label is displayed

Parameters

mode	The display mode for bearing labels.

Returns: true if bearing labels are displayed in this mode, false otherwise.

◆ displayBearingLabel() [2/2]

void TSLTrackGraphicRuler::displayBearingLabel	(	TSLTrackGraphicRuler::LabelDisplayMode	mode,
		bool	display )

Set whether a type of bearing label should be displayed

The application may choose to enable any combination of label modes by calling this method multiple times.

Parameters

mode	The display mode for bearing labels
display	true if the label should be displayed in this mode, false otherwise.

◆ displayDistanceLabel() [1/2]

bool TSLTrackGraphicRuler::displayDistanceLabel ( TSLTrackGraphicRuler::LabelDisplayMode mode ) const

Get whether a type of distance label is displayed

Parameters

mode	The display mode for distance labels.

Returns: true if distance labels are displayed in this mode, false otherwise.

◆ displayDistanceLabel() [2/2]

void TSLTrackGraphicRuler::displayDistanceLabel	(	TSLTrackGraphicRuler::LabelDisplayMode	mode,
		bool	display )

Set whether a type of distance label should be displayed

The application may choose to enable any combination of label modes by calling this method multiple times.

Parameters

mode	The display mode for distance labels
display	true if the label should be displayed in this mode, false otherwise.

◆ displaySymbols() [1/2]

bool TSLTrackGraphicRuler::displaySymbols ( ) const

Get whether symbols will be displayed at the control points

Returns: true if symbols will be displayed, false otherwise

◆ displaySymbols() [2/2]

void TSLTrackGraphicRuler::displaySymbols ( bool display )

Set whether symbols should be displayed at the control points

The rendering of these symbols is controlled via the graphic's rendering attributes

Parameters

display true to display symbols, false otherwise

◆ displayTicks() [1/2]

bool TSLTrackGraphicRuler::displayTicks ( ) const

Get whether ticks are displayed

Returns: true if ticks are displayed, false otherwise

◆ displayTicks() [2/2]

void TSLTrackGraphicRuler::displayTicks ( bool display )

Set whether ticks should be displayed

Parameters

display Whether ticks should be displayed

◆ distanceLabelFactor() [1/2]

double TSLTrackGraphicRuler::distanceLabelFactor ( ) const

Gets the multiplication factor value that is used to calculate the distance units. The factor is only used if the UnitOfMeasure::CustomDistance value is set.

Returns: Currently set multiplication factor which will be applied to a 'CustomDistance' Unit

◆ distanceLabelFactor() [2/2]

void TSLTrackGraphicRuler::distanceLabelFactor ( double factor )

Sets the multiplication factor value that is used to calculate the distance units. The factor is only used if the UnitOfMeasure::CustomDistance value is set. The factor would be applied to a value in metres.

Default value is 0.001. (Displays the distance in kilometres when applied to a distance in metres)

Parameters

factor Multiplication factor

◆ distanceLabelFormat() [1/2]

const char * TSLTrackGraphicRuler::distanceLabelFormat ( TSLTrackGraphicRuler::LabelDisplayMode mode ) const

Get the formatting for the displayed distance label.

Parameters

mode	The Label Display mode that the format string will affect

Returns: The 'printf' style format string code set by the user. Default value is: f

◆ distanceLabelFormat() [2/2]

void TSLTrackGraphicRuler::distanceLabelFormat	(	TSLTrackGraphicRuler::LabelDisplayMode	mode,
		const char *	formatString )

Set the formatting for the displayed distance label.

This function expects a string that is compliant with the C/C++ printf formatting syntax. Passing null or an empty string will revert the formatting to display the default distance formatting. If the TSLTrackGraphicRuler::UnitOfMeasure used is a standard UoM, reverting the formatting will ensure the distance label has the associated suffix when it is displayed.

Passing an empty string will display just the value.

Examples:

"%0.4f" - 42.0000
"%0.1fKm" - 42.0Km
"%eKm" - Distance in Km, using scientific notation

Parameters

mode	The Label Display mode that the format string will affect
formatString	The sequence used to format the displayed distance label value

◆ distanceLabelUnitOfMeasure() [1/2]

TSLTrackGraphicRuler::UnitOfMeasure TSLTrackGraphicRuler::distanceLabelUnitOfMeasure ( ) const

Get the unit of measure for distance labels

Returns: The unit of measure for distance labels

◆ distanceLabelUnitOfMeasure() [2/2]

void TSLTrackGraphicRuler::distanceLabelUnitOfMeasure ( TSLTrackGraphicRuler::UnitOfMeasure uom )

Set the unit of measure for distance labels

The unit of measure determines which units the distance labels are displayed in, and whether fixed/automatic scaling between multiple units are used. The default unit of measure is TSLTrackGraphicRuler::KiloMetres

Parameters

uom	The unit of measure for distance labels

◆ rendering() [1/2]

const TSLRenderingAttributes & TSLTrackGraphicRuler::rendering ( ) const

Get the rendering attributes of the ruler

Returns: The rendering attributes of the ruler

◆ rendering() [2/2]

void TSLTrackGraphicRuler::rendering ( const TSLRenderingAttributes & attribs )

Set the rendering attributes of the ruler

The ruler is composed of the following components:

A polyline which defines the base of the ruler
Multiple symbols which are placed at each of the control points
Text annotations which are placed at each of the control points

A single set of rendering attributes is used for all components of the ruler

◆ tickDistance() [1/2]

double TSLTrackGraphicRuler::tickDistance ( ) const

Get the minimum distance between ticks

The units of this distance are specified by tickDistanceUnitOfMeasure

Returns: The minimum distance between ticks

◆ tickDistance() [2/2]

void TSLTrackGraphicRuler::tickDistance ( double distance )

Set the minimum distance between ticks

The distance used when displaying ticks may be rounded up.
See also
tickDistanceRound
The distance used will also take tickDistanceDU into account to ensure the ticks are kept separate on the display
The default value is 10Km
The unit of measure may be set via tickDistanceUnitOfMeasure

Parameters

distance The minimum distance between ticks

◆ tickDistanceDU() [1/2]

TSLDeviceUnits TSLTrackGraphicRuler::tickDistanceDU ( ) const

Get the minimum distance between ticks in device units

Returns: The minimum distance between ticks in DU

◆ tickDistanceDU() [2/2]

void TSLTrackGraphicRuler::tickDistanceDU ( TSLDeviceUnits distanceDU )

Set the minimum distance between ticks in device units

The actual distance between ticks will depend on this value, tickDistance, and the current zoom level of the display
This limit will be applied after tickDistance to ensure that the display does not become too crowded
The default value is 10

Parameters

distanceDU The minimum distance between ticks in DU

◆ tickDistanceRound() [1/2]

bool TSLTrackGraphicRuler::tickDistanceRound ( ) const

Get whether tick distances are rounded up

Returns: true if tick distances are rounded, false otherwise

◆ tickDistanceRound() [2/2]

void TSLTrackGraphicRuler::tickDistanceRound ( bool round )

Set whether tick distances should be rounded up

If enabled the distance between ticks will be rounded up to the nearest power of 10 once tickDistance and tickDistanceDU have been taken into account. Rounding will be performing in the tickDistanceUnitOfMeasure.

By default this option is enabled

Parameters

round Whether tick distances should be rounded up

◆ tickDistanceUnitOfMeasure() [1/2]

TSLTrackGraphicRuler::UnitOfMeasure TSLTrackGraphicRuler::tickDistanceUnitOfMeasure ( ) const

Get the unit of measure for tick distances

Returns: The unit of measure for tickDistance

◆ tickDistanceUnitOfMeasure() [2/2]

void TSLTrackGraphicRuler::tickDistanceUnitOfMeasure ( TSLTrackGraphicRuler::UnitOfMeasure uom )

Set the unit of measure for tick distances

The default value is TSLTrackGraphicRuler::Metres

Parameters

uom	The unit of measure for tickDistance

◆ tickLength() [1/2]

double TSLTrackGraphicRuler::tickLength ( ) const

Get the length of ticks

Returns: The length of ticks. Units are defined by tickLengthUnits

◆ tickLength() [2/2]

void TSLTrackGraphicRuler::tickLength	(	double	length,
		TSLDimensionUnits	units )

Set the length of ticks

Parameters

length	The length of the ticks
units	The units of the tick length

◆ tickLengthUnits()

TSLDimensionUnits TSLTrackGraphicRuler::tickLengthUnits ( ) const

Get the units of the tick length

Returns: The units of the tick length

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ LabelDisplayMode

◆ UnitOfAngularMeasure

◆ UnitOfMeasure

Member Function Documentation

◆ bearingLabelFactor() [1/2]

◆ bearingLabelFactor() [2/2]

◆ bearingLabelFormat() [1/2]

◆ bearingLabelFormat() [2/2]

◆ bearingLabelUnitOfMeasure() [1/2]

◆ bearingLabelUnitOfMeasure() [2/2]

◆ create()

◆ createTextLabel()

◆ displayBearingLabel() [1/2]

◆ displayBearingLabel() [2/2]

◆ displayDistanceLabel() [1/2]

◆ displayDistanceLabel() [2/2]

◆ displaySymbols() [1/2]

◆ displaySymbols() [2/2]

◆ displayTicks() [1/2]

◆ displayTicks() [2/2]

◆ distanceLabelFactor() [1/2]

◆ distanceLabelFactor() [2/2]

◆ distanceLabelFormat() [1/2]

◆ distanceLabelFormat() [2/2]

◆ distanceLabelUnitOfMeasure() [1/2]

◆ distanceLabelUnitOfMeasure() [2/2]

◆ rendering() [1/2]

◆ rendering() [2/2]

◆ tickDistance() [1/2]

◆ tickDistance() [2/2]

◆ tickDistanceDU() [1/2]

◆ tickDistanceDU() [2/2]

◆ tickDistanceRound() [1/2]

◆ tickDistanceRound() [2/2]

◆ tickDistanceUnitOfMeasure() [1/2]

◆ tickDistanceUnitOfMeasure() [2/2]

◆ tickLength() [1/2]

◆ tickLength() [2/2]

◆ tickLengthUnits()