#include <cartotype_legend.h>

Inheritance diagram for CartoTypeCore::Legend:

Public Member Functions
	Legend (Framework &aFramework)

	Legend (const Legend &aOther)

Legend &	operator= (const Legend &aOther)

std::unique_ptr< Bitmap >	CreateLegend (Result &aError, double aWidth, const char aUnit, double aScaleDenominator, double aScaleDenominatorInView, const BlendStyleSet aBlendStyleSet=nullptr)

void	Clear ()

int32_t	Pixels (double aDimension, const char *aUnit)

void	AddMapObjectLine (MapObjectType aType, const String &aLayer, FeatureInfo aFeatureInfo, const String &aStringAttrib, const String &aLabel)

void	AddTextLine (const String &aText)

void	AddScaleLine (bool aMetricUnits)

void	AddTurnLine (bool aMetricUnits, bool aAbbreviate)

void	SetMainStyleSheet (const char *aData, size_t aLength)

void	SetExtraStyleSheet (const char *aData, size_t aLength)

void	SetBackgroundColor (Color aColor)

void	SetBorder (Color aColor, double aStrokeWidth, double aRadius, const char *aUnit)

void	SetMarginWidth (double aMarginWidth, const char *aUnit)

void	SetMinLineHeight (double aLineHeight, const char *aUnit)

void	SetLabelWrapWidth (double aWrapWidth, const char *aUnit)

void	SetFontFamily (const String &aFontFamily)

void	SetFontSize (double aFontSize, const char *aUnit)

void	SetTextColor (Color aTextColor)

void	SetDiagramColor (Color aDiagramColor)

void	SetAlignment (Align aAlignment)

void	SetPolygonRotation (double aDegrees)

bool	HasTurnInstruction () const

void	SetTurnInstruction (const MString &aText)

String	TurnInstruction ()

uint32_t	Serial () const

std::shared_ptr< ThreadSafeNavigationState >	NavigationState () const

void	SetNavigationState (std::shared_ptr< ThreadSafeNavigationState > aState)

Detailed Description

The Legend class creates bitmaps showing sample map objects, with optional text lines and a scale, to be used as a map legend or for visualisation in the style sheet editor.

Dimensions are specified with units, which may be "pt" (point), "pc" (pica), "cm" (centimetre), "mm" (millimetre), "in" (inch), or "px" (pixel). An empty or unrecognised unit is taken as "px".

It's relatively expensive to construct a Legend object, so it is best to keep such an object in existence rather than creating one as a temporary object in a draw loop.

Constructor & Destructor Documentation

◆ Legend() [1/2]

CartoTypeCore::Legend::Legend ( Framework & aFramework )

Creates a Legend object with the same fonts and style sheet as aFramework.

◆ Legend() [2/2]

CartoTypeCore::Legend::Legend ( const Legend & aOther )

Creates a Legend object by copying another one.

Member Function Documentation

◆ AddMapObjectLine()

void CartoTypeCore::Legend::AddMapObjectLine	(	MapObjectType	aType,
		const String &	aLayer,
		FeatureInfo	aFeatureInfo,
		const String &	aStringAttrib,
		const String &	aLabel
	)

Adds a line containing a map object, with an optional label to the left of it.

◆ AddScaleLine()

void CartoTypeCore::Legend::AddScaleLine ( bool aMetricUnits )

Adds a scale bar line, using the current font family, font size, alignment, text color, diagram color and minimum line height. If aMetricUnits is true kilometers and meters are used, otherwise miles and yards.

◆ AddTextLine()

void CartoTypeCore::Legend::AddTextLine ( const String & aText )

Adds a line of text, using the current font family, font size, text color and minimum line height.

◆ AddTurnLine()

void CartoTypeCore::Legend::AddTurnLine	(	bool	aMetricUnits,
		bool	aAbbreviate
	)

Adds a turn line, using the current font family, font size, alignment, text color, diagram color and minimum line height. If aMetricUnits is true kilometers and meters are used for the distance to the turn, otherwise miles and yards.

◆ Clear()

void CartoTypeCore::Legend::Clear ( )

Deletes all legend lines (map objects, text lines and scale bars).

◆ CreateLegend()

std::unique_ptr< Bitmap > CartoTypeCore::Legend::CreateLegend	(	Result &	aError,
		double	aWidth,
		const char *	aUnit,
		double	aScaleDenominator,
		double	aScaleDenominatorInView,
		const BlendStyleSet *	aBlendStyleSet = `nullptr`
	)

Creates a legend bitmap for the current set of map objects, text lines and scale bars.

In general you should not call this function from application code. It is called automatically when necessary if you add a legend or other notice using Framework::SetLegend, Framework::SetCopyright, etc.

The parameter aWidth does not include the width of any labels drawn to the left of map objects.

The scales are used like this: aScaleDenominator is used to compile the style sheet, and aScaleDenominatorInView is used to draw the scale bar if any; it is the local scale, as opposed to the projection's scale. They can be very different where there is great distortion, as when using the Mercator projection and displaying an area a long way from the equator.

If there is an error, an empty bitmap is returned.

◆ HasTurnInstruction()

bool CartoTypeCore::Legend::HasTurnInstruction ( ) const

Returns true if any of the lines of this legend object is a turn instruction.

◆ NavigationState()

std::shared_ptr< ThreadSafeNavigationState > CartoTypeCore::Legend::NavigationState ( ) const

Returns the current navigation state. For internal use.

◆ operator=()

Legend & CartoTypeCore::Legend::operator= ( const Legend & aOther )

The assignment operator: copies aOther to this Legend.

◆ Pixels()

int32_t CartoTypeCore::Legend::Pixels	(	double	aDimension,
		const char *	aUnit
	)

Returns the rounded number of pixels corresponding to a certain dimension and unit. If aUnit is null the unit is pixels.

◆ Serial()

uint32_t CartoTypeCore::Legend::Serial ( ) const

Returns the serial number of the navigation state, used to check whether the state has been changed by the framework.

◆ SetAlignment()

void CartoTypeCore::Legend::SetAlignment ( Align aAlignment )

Sets the alignment for labels and scale bars.

◆ SetBackgroundColor()

void CartoTypeCore::Legend::SetBackgroundColor ( Color aColor )

Sets the background color. Transparent colors are allowed.

◆ SetBorder()

void CartoTypeCore::Legend::SetBorder	(	Color	aColor,
		double	aStrokeWidth,
		double	aRadius,
		const char *	aUnit
	)

Sets the border color and corner radius for the whole legend. Transparent border colors are allowed.

◆ SetDiagramColor()

void CartoTypeCore::Legend::SetDiagramColor ( Color aDiagramColor )

Sets the diagram color, used for scale bars and turn diagrams, for subsequently added lines.

◆ SetExtraStyleSheet()

void CartoTypeCore::Legend::SetExtraStyleSheet	(	const char *	aData,
		size_t	aLength
	)

Sets the extra style sheet.

The purpose of this function is to allow a caller such as a style sheet editor to create an extra style sheet containing a single layer, or a small number of layers, and draw a legend for that layer only.

◆ SetFontFamily()

void CartoTypeCore::Legend::SetFontFamily ( const String & aFontFamily )

Sets the font family for subsequently added lines.

◆ SetFontSize()

void CartoTypeCore::Legend::SetFontSize	(	double	aFontSize,
		const char *	aUnit
	)

Sets the font size for subsequently added lines.

◆ SetLabelWrapWidth()

void CartoTypeCore::Legend::SetLabelWrapWidth	(	double	aWrapWidth,
		const char *	aUnit
	)

Sets the label wrap width for subsequently added lines. Values of zero or less prevent wrapping.

◆ SetMainStyleSheet()

void CartoTypeCore::Legend::SetMainStyleSheet	(	const char *	aData,
		size_t	aLength
	)

Sets the main style sheet, replacing the style sheet copied from the Framework parameter to the Legend constructor.

◆ SetMarginWidth()

void CartoTypeCore::Legend::SetMarginWidth	(	double	aMarginWidth,
		const char *	aUnit
	)

Sets the margin width for the whole legend.

◆ SetMinLineHeight()

void CartoTypeCore::Legend::SetMinLineHeight	(	double	aLineHeight,
		const char *	aUnit
	)

Sets the minimum line height for subsequently added lines.

◆ SetNavigationState()

void CartoTypeCore::Legend::SetNavigationState ( std::shared_ptr< ThreadSafeNavigationState > aState )

Sets the navigation state. For internal use.

◆ SetPolygonRotation()

void CartoTypeCore::Legend::SetPolygonRotation ( double aDegrees )

Sets the amount in degrees by which rectangles drawn for polygon legend lines are rotated, for subsequently added lines.

◆ SetTextColor()

void CartoTypeCore::Legend::SetTextColor ( Color aTextColor )

Sets the text color for subsequently added lines.

◆ SetTurnInstruction()

void CartoTypeCore::Legend::SetTurnInstruction ( const MString & aText )

Sets the instruction to be displayed for the current turn, overriding automatically generated instructions. To revert to automatically generated instructions, call this function with empty text.

◆ TurnInstruction()

String CartoTypeCore::Legend::TurnInstruction ( )

Returns the instruction to be displayed for the current turn, overriding automatically generated instructions. Returns the empty string if automatically generated instructions are used and there is no overriding instruction.

The documentation for this class was generated from the following files:

cartotype_legend.h
cartotype_legend.cpp

Public Member Functions