CartoType C++ API 7.8.2, 2022-03-25
for Windows, Linux, Qt and other platforms supporting C++ development
Public Member Functions | List of all members
CartoType::CLegend Class Reference

#include <cartotype_legend.h>

Inheritance diagram for CartoType::CLegend:

Public Member Functions

 CLegend (CFramework &aFramework)
 CLegend (const CLegend &aOther)
CLegendoperator= (const CLegend &aOther)
std::unique_ptr< CBitmapCreateLegend (TResult &aError, double aWidth, const char *aUnit, double aScaleDenominator, double aScaleDenominatorInView, const TBlendStyleSet *aBlendStyleSet=nullptr)
void Clear ()
int32_t Pixels (double aDimension, const char *aUnit)
void AddMapObjectLine (TMapObjectType aType, const CString &aLayer, const char *aOsmType, int32_t aIntAttrib, const CString &aStringAttrib, const CString &aLabel)
void AddTextLine (const CString &aText)
void AddScaleLine (bool aMetricUnits)
void AddTurnLine (bool aMetricUnits, bool aAbbreviate)
void SetMainStyleSheet (const uint8_t *aData, size_t aLength)
void SetExtraStyleSheet (const uint8_t *aData, size_t aLength)
void SetBackgroundColor (TColor aColor)
void SetBorder (TColor 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 CString &aFontFamily)
void SetFontSize (double aFontSize, const char *aUnit)
void SetTextColor (TColor aTextColor)
void SetDiagramColor (TColor aDiagramColor)
void SetAlignment (TAlign aAlignment)
void SetPolygonRotation (double aDegrees)
bool HasTurnInstruction () const
void SetTurnInstruction (const MString &aText)
CString TurnInstruction ()
uint32_t Serial () const
std::shared_ptr< CThreadSafeNavigationState > NavigationState () const
void SetNavigationState (std::shared_ptr< CThreadSafeNavigationState > aState)

Detailed Description

The CLegend 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 CLegend 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

◆ CLegend() [1/2]

CartoType::CLegend::CLegend ( CFramework aFramework)

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

◆ CLegend() [2/2]

CartoType::CLegend::CLegend ( const CLegend aOther)

Creates a CLegend object by copying another one.

Member Function Documentation

◆ AddMapObjectLine()

void CartoType::CLegend::AddMapObjectLine ( TMapObjectType  aType,
const CString aLayer,
const char *  aOsmType,
int32_t  aIntAttrib,
const CString aStringAttrib,
const CString aLabel 

Adds a line containing a map object, with an optional label to the left of it. If the parameter aOsmType is a type code made from three lower-case letters in the range a...z, it is converted to an integer type code which is ORed with aIntAttrib.

◆ AddScaleLine()

void CartoType::CLegend::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 CartoType::CLegend::AddTextLine ( const CString aText)

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

◆ AddTurnLine()

void CartoType::CLegend::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 CartoType::CLegend::Clear ( )

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

◆ CreateLegend()

std::unique_ptr< CBitmap > CartoType::CLegend::CreateLegend ( TResult aError,
double  aWidth,
const char *  aUnit,
double  aScaleDenominator,
double  aScaleDenominatorInView,
const TBlendStyleSet 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 CFramework::SetLegend, CFramework::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 CartoType::CLegend::HasTurnInstruction ( ) const

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

◆ NavigationState()

std::shared_ptr< CThreadSafeNavigationState > CartoType::CLegend::NavigationState ( ) const

Returns the current navigation state. For internal use.

◆ operator=()

CLegend & CartoType::CLegend::operator= ( const CLegend aOther)

The assignment operator: copies aOther to this CLegend.

◆ Pixels()

int32_t CartoType::CLegend::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 CartoType::CLegend::Serial ( ) const

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

◆ SetAlignment()

void CartoType::CLegend::SetAlignment ( TAlign  aAlignment)

Sets the alignment for labels and scale bars.

◆ SetBackgroundColor()

void CartoType::CLegend::SetBackgroundColor ( TColor  aColor)

Sets the background color. Transparent colors are allowed.

◆ SetBorder()

void CartoType::CLegend::SetBorder ( TColor  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 CartoType::CLegend::SetDiagramColor ( TColor  aDiagramColor)

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

◆ SetExtraStyleSheet()

void CartoType::CLegend::SetExtraStyleSheet ( const uint8_t *  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 CartoType::CLegend::SetFontFamily ( const CString aFontFamily)

Sets the font family for subsequently added lines.

◆ SetFontSize()

void CartoType::CLegend::SetFontSize ( double  aFontSize,
const char *  aUnit 

Sets the font size for subsequently added lines.

◆ SetLabelWrapWidth()

void CartoType::CLegend::SetLabelWrapWidth ( double  aWrapWidth,
const char *  aUnit 

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

◆ SetMainStyleSheet()

void CartoType::CLegend::SetMainStyleSheet ( const uint8_t *  aData,
size_t  aLength 

Sets the main style sheet, replacing the style sheet copied from the CFramework parameter to the CLegend constructor.

◆ SetMarginWidth()

void CartoType::CLegend::SetMarginWidth ( double  aMarginWidth,
const char *  aUnit 

Sets the margin width for the whole legend.

◆ SetMinLineHeight()

void CartoType::CLegend::SetMinLineHeight ( double  aLineHeight,
const char *  aUnit 

Sets the minimum line height for subsequently added lines.

◆ SetNavigationState()

void CartoType::CLegend::SetNavigationState ( std::shared_ptr< CThreadSafeNavigationState >  aState)

Sets the navigation state. For internal use.

◆ SetPolygonRotation()

void CartoType::CLegend::SetPolygonRotation ( double  aDegrees)

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

◆ SetTextColor()

void CartoType::CLegend::SetTextColor ( TColor  aTextColor)

Sets the text color for subsequently added lines.

◆ SetTurnInstruction()

void CartoType::CLegend::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()

CString CartoType::CLegend::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: