A graphics primitive representing a block of styled text. More...

#include <TextBlockPrimitive2D.hpp>

Inheritance diagram for CDPL::Vis::TextBlockPrimitive2D:

Public Types
typedef std::shared_ptr< TextBlockPrimitive2D >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated `TextBlockPrimitive2D` instances. More...

Public Types inherited from CDPL::Vis::GraphicsPrimitive2D
typedef std::shared_ptr< GraphicsPrimitive2D >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated `GraphicsPrimitive2D` instances. More...

Public Member Functions
	TextBlockPrimitive2D ()
	Construct an empty text block primitive at position (0, 0). More...

void	render (Renderer2D &renderer) const
	Visualizes the graphics primitive by means of the Renderer2D instance renderer. More...

void	setText (const std::string &text)
	Specifies the block's text content. More...

void	clearText ()
	Clears the block's text content. More...

const std::string &	getText () const
	Returns the block's text content. More...

bool	hasText () const
	Tells whether the text block has any visible text (includes whitespace). More...

void	setPosition (const Math::Vector2D &pos)
	Sets the position of the text block in 2D space. More...

void	setPosition (double x, double y)
	Sets the position of the text block to (x, y). More...

const Math::Vector2D &	getPosition () const
	Returns the position of the text block. More...

void	setPen (const Pen &pen)
	Sets the pen defining the default text color. More...

const Pen &	getPen () const
	Returns the pen defining the default text color. More...

void	setFont (const Font &font)
	Sets the font used for text rendering. More...

const Font &	getFont () const
	Returns the font used for text rendering. More...

void	setAlignment (unsigned int alignment)
	Specifies the way lines should be horizontally aligned. More...

unsigned int	getAlignment () const
	Returns the active horizontal text alignment specification. More...

void	setLineSpacing (double spacing)
	Sets the line spacing value. More...

double	getLineSpacing () const
	Returns the active line spacing value. More...

void	layout (FontMetrics &font_metrics)
	Performs a layout of the text for the currently specified font using the provided Vis::FontMetrics instance font_metrics. More...

GraphicsPrimitive2D::SharedPointer	clone () const
	Creates a dynamically allocated copy of the graphics primitive. More...

void	getBounds (Rectangle2D &bounds, FontMetrics *font_metrics) const
	Calculates the bounds of the graphics primitive. More...

Public Member Functions inherited from CDPL::Vis::GraphicsPrimitive2D
virtual	~GraphicsPrimitive2D ()
	Virtual destructor. More...

Detailed Description

A graphics primitive representing a block of styled text.

Class TextBlockPrimitive2D is smiliar to Vis::TextLabelPrimitive2D but way more versatile. TextBlockPrimitive2D can store/render text that spans multiple lines with configurable line spacing (see setLineSpacing()) and alignment (see setAlignment()), and supports changing text color and various attributes like font weight and slant for individual text portions. Furthermore, text fragments can be rendered sub/super-scripted, under- and overlined as well as striked out. This is achieved by using an XML-based syntax where a portion of text to be rendered in a particular style is enclosed in specific start and end tags. More information on the syntax, the supported styling tags and their meaning can be found in the documentation of the method setText().

Member Typedef Documentation

◆ SharedPointer

typedef std::shared_ptr<TextBlockPrimitive2D> CDPL::Vis::TextBlockPrimitive2D::SharedPointer

A reference-counted smart pointer [SHPTR] for dynamically allocated TextBlockPrimitive2D instances.

Constructor & Destructor Documentation

◆ TextBlockPrimitive2D()

CDPL::Vis::TextBlockPrimitive2D::TextBlockPrimitive2D ( )

Construct an empty text block primitive at position (0, 0).

Member Function Documentation

◆ render()

void CDPL::Vis::TextBlockPrimitive2D::render ( Renderer2D & renderer ) const

virtual

Visualizes the graphics primitive by means of the Renderer2D instance renderer.

Parameters

renderer The renderer that performs the drawing operations.

Implements CDPL::Vis::GraphicsPrimitive2D.

◆ setText()

void CDPL::Vis::TextBlockPrimitive2D::setText ( const std::string & text )

Specifies the block's text content.

Color, font attributes and style of individual text fragments can be controlled by enclosing the concerned piece of text in specific XML tags. The following tags are supported:

Tag	Effect/Description
<br/>	Line break
<b>	Boldfaced text
<i>	Italicized text
<o>	Overlined text
<u>	Underlined text
<s>	Striked-out text
<sub>	Subscripted text
<sup>	Superscripted text
<color>	Text color; supports the attributes r, g, b and a with a value in the range [0.0, 1.0]; default component values are r=0, b=0, g=0 and a=1

Newline characters \n are regarded and interpreted as such. Tab characters \t are replaced by a single whitespace character. Any other special characters are deleted. The supported tags listed above are all optional. Plain ASCII text will thus be rendered using the set font (see setFont()) and color (see setPen()).

Parameters

text	The text content of the block.

Exceptions

Base::ValueError if XML parsing of the specified text failed.

◆ clearText()

void CDPL::Vis::TextBlockPrimitive2D::clearText ( )

Clears the block's text content.

◆ getText()

const std::string& CDPL::Vis::TextBlockPrimitive2D::getText ( ) const

Returns the block's text content.

Returns: The text content of the block.

◆ hasText()

bool CDPL::Vis::TextBlockPrimitive2D::hasText ( ) const

Tells whether the text block has any visible text (includes whitespace).

Returns: true if there is any visible text and false otherwise.

◆ setPosition() [1/2]

void CDPL::Vis::TextBlockPrimitive2D::setPosition ( const Math::Vector2D & pos )

Sets the position of the text block in 2D space.

The position specifies the upper-left corner of the text block's bounding box.

Parameters

pos	Theposition of the text block.

◆ setPosition() [2/2]

void CDPL::Vis::TextBlockPrimitive2D::setPosition	(	double	x,
		double	y
	)

Sets the position of the text block to (x, y).

The position specifies the upper-left corner of the text block's bounding box.

Parameters

x	The x-position of the text block.
y	The y-position of the baseline.

◆ getPosition()

const Math::Vector2D& CDPL::Vis::TextBlockPrimitive2D::getPosition ( ) const

Returns the position of the text block.

Returns: The position of the text block.

See also: setPosition()

◆ setPen()

void CDPL::Vis::TextBlockPrimitive2D::setPen ( const Pen & pen )

Sets the pen defining the default text color.

Parameters

pen	The pen defining the default text color.

◆ getPen()

const Pen& CDPL::Vis::TextBlockPrimitive2D::getPen ( ) const

Returns the pen defining the default text color.

Returns: The pen defining the default text color.

◆ setFont()

void CDPL::Vis::TextBlockPrimitive2D::setFont ( const Font & font )

Sets the font used for text rendering.

Parameters

font	The font used for text rendering.

Note: Calling this method invalidates the current layout (see layout()).

◆ getFont()

const Font& CDPL::Vis::TextBlockPrimitive2D::getFont ( ) const

Returns the font used for text rendering.

Returns: The font used for text rendering.

◆ setAlignment()

void CDPL::Vis::TextBlockPrimitive2D::setAlignment ( unsigned int alignment )

Specifies the way lines should be horizontally aligned.

Possible horizontal alignment values are defined in namespace Vis::Alignment.

Parameters

alignment The horizontal text alignment specification.

◆ getAlignment()

unsigned int CDPL::Vis::TextBlockPrimitive2D::getAlignment ( ) const

Returns the active horizontal text alignment specification.

Possible horizontal alignment values are defined in namespace Vis::Alignment.

Returns: The current horizontal text alignment specification.

◆ setLineSpacing()

void CDPL::Vis::TextBlockPrimitive2D::setLineSpacing ( double spacing )

Sets the line spacing value.

The final base line spacing is the product of the specified line spacing and the font height returned by the method Vis::FontMetrics::getHeight() for the set font.

Parameters

spacing The desired line spacing.

◆ getLineSpacing()

double CDPL::Vis::TextBlockPrimitive2D::getLineSpacing ( ) const

Returns the active line spacing value.

Returns: The line spacing value.

◆ layout()

void CDPL::Vis::TextBlockPrimitive2D::layout ( FontMetrics & font_metrics )

Performs a layout of the text for the currently specified font using the provided Vis::FontMetrics instance font_metrics.

Parameters

font_metrics An instance of a class implementing the Vis::FontMetrics interface.

Note: This method must be called before the text is rendered by calling the method render(). The methods setText() or setFont() invalidate the text layout.

◆ clone()

GraphicsPrimitive2D::SharedPointer CDPL::Vis::TextBlockPrimitive2D::clone ( ) const

virtual

Creates a dynamically allocated copy of the graphics primitive.

Returns: The copy of the graphics primitive.

Implements CDPL::Vis::GraphicsPrimitive2D.

◆ getBounds()

void CDPL::Vis::TextBlockPrimitive2D::getBounds	(	Rectangle2D &	bounds,
		FontMetrics *	font_metrics
	)		const

virtual

Calculates the bounds of the graphics primitive.

Parameters

bounds	The object storing the calculated bounding box.
font_metrics	The font metrics object to use for bounds calculation (if required).

Implements CDPL::Vis::GraphicsPrimitive2D.

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

TextBlockPrimitive2D.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ SharedPointer

Constructor & Destructor Documentation

◆ TextBlockPrimitive2D()

Member Function Documentation

◆ render()

◆ setText()

◆ clearText()

◆ getText()

◆ hasText()

◆ setPosition() [1/2]

◆ setPosition() [2/2]

◆ getPosition()

◆ setPen()

◆ getPen()

◆ setFont()

◆ getFont()

◆ setAlignment()

◆ getAlignment()

◆ setLineSpacing()

◆ getLineSpacing()

◆ layout()

◆ clone()

◆ getBounds()