#include <CULabel.h>

Inheritance diagram for cugl::scene2::Label:

Public Types
enum	HAlign : int { HAlign::LEFT = 0, HAlign::CENTER = 1, HAlign::RIGHT = 2, HAlign::HARDLEFT = 3, HAlign::TRUECENTER = 4, HAlign::HARDRIGHT = 5 }

enum	VAlign { VAlign::BOTTOM = 0, VAlign::MIDDLE = 1, VAlign::TOP = 2, VAlign::HARDBOTTOM = 3, VAlign::TRUEMIDDLE = 4, VAlign::HARDTOP = 5 }

Public Member Functions
	Label ()

	~Label ()

virtual void	dispose () override

virtual bool	init () override

bool	init (const Size size, const std::shared_ptr< Font > &font)

bool	initWithText (const char *text, const std::shared_ptr< Font > &font)

bool	initWithText (const std::string &text, const std::shared_ptr< Font > &font)

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override

const std::string &	getText () const

virtual void	setText (const std::string &text, bool resize=false)

const Vec2	getPadding () const

float	getPaddingX () const

float	getPaddingY () const

void	setPadding (const Vec2 padding)

void	setPadding (float padx, float pady)

void	setPaddingX (float padx)

void	setPaddingY (float pady)

HAlign	getHorizontalAlignment () const

void	setHorizontalAlignment (HAlign halign)

VAlign	getVerticalAlignment () const

void	setVerticalAlignment (VAlign valign)

const Rect	getTextBounds () const

const Rect	getTrueBounds () const

float	getBaseLine () const

virtual void	setContentSize (const Size size) override

virtual void	setContentSize (float width, float height) override

Color4	getForeground () const

void	setForeground (Color4 color)

Color4	getBackground () const

void	setBackground (Color4 color)

std::shared_ptr< Font >	getFont () const

void	setFont (const std::shared_ptr< Font > &font, bool resize=false)

void	setBlendFunc (GLenum srcFactor, GLenum dstFactor)

GLenum	getSourceBlendFactor () const

GLenum	getDestinationBlendFactor () const

void	setBlendEquation (GLenum equation)

GLenum	getBlendEquation () const

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Mat4 &transform, Color4 tint) override

Public Member Functions inherited from cugl::scene2::SceneNode
	SceneNode ()

	~SceneNode ()

virtual bool	initWithPosition (const Vec2 pos)

bool	initWithPosition (float x, float y)

virtual bool	initWithBounds (const Size size)

bool	initWithBounds (float width, float height)

virtual bool	initWithBounds (const Rect rect)

bool	initWithBounds (float x, float y, float width, float height)

virtual SceneNode *	copy (SceneNode *dst)

unsigned int	getTag () const

void	setTag (unsigned int tag)

const std::string &	getName () const

void	setName (const std::string &name)

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

const Vec2	getPosition () const

void	setPosition (const Vec2 &position)

void	setPosition (float x, float y)

float	getPositionX (void) const

void	setPositionX (float x)

float	getPositionY (void) const

void	setPositionY (float y)

Vec2	getWorldPosition () const

const Size	getContentSize () const

float	getContentWidth () const

void	setContentWidth (float width)

float	getContentHeight () const

void	setContentHeight (float height)

Size	getSize () const

float	getWidth () const

float	getHeight () const

Rect	getBoundingBox () const

virtual void	setAnchor (const Vec2 anchor)

void	setAnchor (float x, float y)

const Vec2	getAnchor () const

Vec2	getAnchorInPixels ()

Color4	getColor () const

virtual void	setColor (Color4 color)

Color4	getAbsoluteColor ()

bool	isVisible () const

void	setVisible (bool visible)

bool	hasRelativeColor ()

void	setRelativeColor (bool flag)

std::shared_ptr< Scissor >	getScissor () const

void	setScissor (const std::shared_ptr< Scissor > &scissor)

void	setScissor ()

const Vec2	getScale () const

float	getScaleX () const

float	getScaleY () const

void	setScale (float scale)

void	setScale (const Vec2 vec)

void	setScale (float sx, float sy)

float	getAngle ()

void	setAngle (float angle)

const Mat4 &	getAlternateTransform ()

void	setAlternateTransform (const Mat4 &transform)

bool	withAlternateTransform ()

void	chooseAlternateTransform (bool active)

const Mat4 &	getNodeToParentTransform () const

Mat4	getParentToNodeTransform () const

Mat4	getNodeToWorldTransform () const

Mat4	getWorldToNodeTransform () const

Vec2	screenToNodeCoords (const Vec2 screenPoint) const

Vec2	worldToNodeCoords (const Vec2 worldPoint) const

Vec2	nodeToScreenCoords (const Vec2 nodePoint) const

Vec2	nodeToWorldCoords (const Vec2 nodePoint) const

Vec2	parentToNodeCoords (const Vec2 parentPoint) const

Vec2	nodeToParentCoords (const Vec2 nodePoint) const

void	setZOrder (int z)

int	getZOrder () const

bool	isZDirty () const

void	sortZOrder ()

size_t	getChildCount () const

std::shared_ptr< SceneNode >	getChild (unsigned int pos)

const std::shared_ptr< SceneNode > &	getChild (unsigned int pos) const

template<typename T >
std::shared_ptr< T >	getChild (unsigned int pos) const

std::shared_ptr< SceneNode >	getChildByTag (unsigned int tag) const

template<typename T >
std::shared_ptr< T >	getChildByTag (unsigned int tag) const

std::shared_ptr< SceneNode >	getChildByName (const std::string name) const

template<typename T >
std::shared_ptr< T >	getChildByName (const std::string name) const

std::vector< std::shared_ptr< SceneNode > >	getChildren ()

const std::vector< std::shared_ptr< SceneNode > > &	getChildren () const

void	addChild (std::shared_ptr< SceneNode > child)

virtual void	addChild (const std::shared_ptr< SceneNode > &child, int zval)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag, int zval)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string &name)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string &name, int zval)

void	swapChild (const std::shared_ptr< SceneNode > &child1, const std::shared_ptr< SceneNode > &child2, bool inherit=false)

SceneNode *	getParent ()

const SceneNode *	getParent () const

Scene2 *	getScene ()

const Scene2 *	getScene () const

void	removeFromParent ()

virtual void	removeChild (unsigned int pos)

void	removeChild (const std::shared_ptr< SceneNode > &child)

void	removeChildByTag (unsigned int tag)

void	removeChildByName (const std::string name)

virtual void	removeAllChildren ()

virtual void	render (const std::shared_ptr< SpriteBatch > &batch, const Mat4 &transform, Color4 tint)

virtual void	render (const std::shared_ptr< SpriteBatch > &batch)

const std::shared_ptr< Layout > &	getLayout () const

void	setLayout (const std::shared_ptr< Layout > &layout)

virtual void	doLayout ()

Static Public Member Functions
static std::shared_ptr< Label >	alloc (const Size size, const std::shared_ptr< Font > &font)

static std::shared_ptr< Label >	alloc (const std::string &text, const std::shared_ptr< Font > &font)

static std::shared_ptr< Label >	alloc (const char *text, const std::shared_ptr< Font > &font)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNode >	alloc ()

static std::shared_ptr< SceneNode >	allocWithPosition (const Vec2 pos)

static std::shared_ptr< SceneNode >	allocWithPosition (float x, float y)

static std::shared_ptr< SceneNode >	allocWithBounds (const Size size)

static std::shared_ptr< SceneNode >	allocWithBounds (float width, float height)

static std::shared_ptr< SceneNode >	allocWithBounds (const Rect rect)

static std::shared_ptr< SceneNode >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Protected Attributes
std::shared_ptr< Font >	_font

std::string	_text

Rect	_textbounds

Rect	_truebounds

Vec2	_padding

HAlign	_halign

VAlign	_valign

Color4	_foreground

Color4	_background

GLenum	_blendEquation

GLenum	_srcFactor

GLenum	_dstFactor

bool	_rendered

Mesh< SpriteVertex2 >	_mesh

Rect	_bounds

std::shared_ptr< Texture >	_texture

Protected Attributes inherited from cugl::scene2::SceneNode
Vec2	_position

Vec2	_anchor

Size	_contentSize

Color4	_tintColor

bool	_hasParentColor

bool	_isVisible

std::shared_ptr< Scissor >	_scissor

Vec2	_scale

float	_angle

Mat4	_transform

bool	_useTransform

Mat4	_combined

std::vector< std::shared_ptr< SceneNode > >	_children

SceneNode *	_parent

Scene2 *	_graph

std::shared_ptr< Layout >	_layout

int	_childOffset

unsigned int	_tag

std::string	_name

size_t	_hashOfName

int	_zOrder

bool	_zDirty

std::shared_ptr< JsonValue >	_json

Detailed Description

This class is a node the represents a single line of text.

This class only represents a single line of text. To have a node that represents multiple lines with spacing and justitication, you should use the (as yet unimplemented) MultilineLabel class.

By default, the content size is just large enough to render the text given. If you reset the content size to larger than the what the text needs, the the text is placed in the label according to the text bounds. If you reset it to smaller, the text may be cut off in rendering.

If the background color is not clear, then the label will have a colored backing rectangle. The rectangle will extended from the origin to the content size in Node space.

To display the text, you need a Font. The rendering style of the font will depend on whether or not it has an atlas. We highly recommend an atlas if you have a lot of labels using the same font or if the text changes rapidly. In our experience, generating a simple "Hello World!" label is 1-2 orders of magnitude faster with an atlas. The only time to use a font without an atlas is if you have relatively few labels and they never change at all.

Member Enumeration Documentation

◆ HAlign

enum cugl::scene2::Label::HAlign : int

strong

This enumeration represents the horizontal alignment of text in a Label.

Horizontal alignment can be interpretted in two ways. First, it can be the relationship between the text and it surrounding bounding box. Alternatively, it can mean justification, which is the relationship of multiple lines of text. The latter is reserved for the (as yet unimplemented) MultilineLabel class.

Enumerator
LEFT	Anchors the text on the left side of the label If the initial character has any natural spacing on the left-hand side (e.g the character width is less than the advance), this will be included.
CENTER	Anchors the text in the center horiontal position of the label. Centering will include any natural spacing (e.g the character width is less than the advance) around the first and last character.
RIGHT	Anchors the text on the right side of the label If the final character has any natural spacing on the right-hand side (e.g the character width is less than the advance), this will be included.
HARDLEFT	Anchors the text on the left side of the label Any natural spacing on the left of the first character will be ignored. Hence the character will begin drawing at the very edge of the label.
TRUECENTER	Anchors the text in the center horiontal position of the label. Centering will ignore any natural spacing around the first and last character. Hence the text will be measure from the left edge of the first character to the right edge of the second.
HARDRIGHT	Anchors the text on the right side of the label. Any natural spacing on the right of the last character will be ignored. Hence the character will stop drawing at the very edge of the label.

◆ VAlign

enum cugl::scene2::Label::VAlign

strong

This enumeration represents the vertical alignment of text in a Label.

Vertical alignment is always interprettes as the relationship between the text and it surrounding bounding box.

Enumerator
BOTTOM	Anchors the text at the bottom of the label This option uses the font descent in placing the characters. Hence if no character is below the baseline, this descent will be included as spacing at the bottom.
MIDDLE	Anchors the text at the middle vertical position of the label This option uses the font height in placing the characters. Hence if no character is below the baseline, this descent will be included as spacing at the bottom. In addition, if no character is reaches the maximum above baseline, the ascent will be included as spacing at the top.
TOP	Anchors the text at the top of the label This option uses the font ascent in placing the characters. Hence if no character is reaches the maximum above baseline, this ascent will be included as spacing at the top.
HARDBOTTOM	Anchors the text at the bottom of the label This option ignores the font descent in placing the characters. It places the characters so that the one with the greatest extent below the base line is at the very bottom edge of the label.
TRUEMIDDLE	Anchors the text at the middle vertical position of the label This option ignores the font height in placing the characters. It measure the characters from the top of the highest character to the bottom of the character with greatest extend below the baseline.
HARDTOP	Anchors the text at the top of the label This option ignores the font ascent in placing the characters. It places the characters so that the one with the greatest extent above the baseline is at the very top edge of the label.

Constructor & Destructor Documentation

◆ Label()

cugl::scene2::Label::Label ( )

Creates an uninitialized label with no text or font information.

You must initialize this Label before use.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a Node on the heap, use one of the static constructors instead.

◆ ~Label()

cugl::scene2::Label::~Label ( )

inline

Deletes this label, disposing all resources

Member Function Documentation

◆ alloc() [1/3]

static std::shared_ptr<Label> cugl::scene2::Label::alloc	(	const char *	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated label with the given text and font

The text string will be purged of all non-printable characters. If any glyphs are missing from the font atlas, they will not be rendered.

The label will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

All unprintable characters will be removed from the string. This includes tabs and newlines. They will be replaced by spaces. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters

text	The text to display in the label
font	The font for this label

Returns: a newly allocated label with the given text and font atlas

◆ alloc() [2/3]

static std::shared_ptr<Label> cugl::scene2::Label::alloc	(	const Size	size,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated label with the given size and font

The text is empty and may be set later with setText().

Parameters

size	The size of the label to display
font	The font for this label

Returns: a newly allocated label with the given size and font atlas

◆ alloc() [3/3]

static std::shared_ptr<Label> cugl::scene2::Label::alloc	(	const std::string &	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated label with the given text and font

The label will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

All unprintable characters will be removed from the string. This includes tabs and newlines. They will be replaced by spaces. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters

text	The text to display in the label
font	The font for this label

Returns: a newly allocated label with the given text and font atlas

◆ allocWithData()

static std::shared_ptr<SceneNode> cugl::scene2::Label::allocWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

inlinestatic

Returns a newly allocated node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "font":         The name of a previously loaded font asset
 "text":         The initial label text
 "foreground":   A four-element integer array. Values should be 0..255
 "background":   A four-element integer array. Values should be 0..255
 "padding":      A two-element float array.
 "halign":       One of 'left', 'center', 'right', 'hard left',
                 'true center' and 'hard right'.
 "valign":       One of 'top', 'middle', 'bottom', 'hard top',
                 'true middle' and 'hard bottom'.

The attribute 'font' is REQUIRED. All other attributes are optional.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: a newly allocated node with the given JSON specificaton.

◆ dispose()

virtual void cugl::scene2::Label::dispose ( )

overridevirtual

Disposes all of the resources used by this label.

A disposed Label can be safely reinitialized. Any children owned by this node will be released. They will be deleted if no other object owns them.

It is unsafe to call this on a Label that is still currently inside of a scene graph.

Reimplemented from cugl::scene2::SceneNode.

Reimplemented in cugl::scene2::TextField.

◆ draw()

virtual void cugl::scene2::Label::draw	(	const std::shared_ptr< SpriteBatch > &	batch,
		const Mat4 &	transform,
		Color4	tint
	)

overridevirtual

Draws this Node via the given SpriteBatch.

This method only worries about drawing the current node. It does not attempt to render the children.

This is the method that you should override to implement your custom drawing code. You are welcome to use any OpenGL commands that you wish. You can even skip use of the SpriteBatch. However, if you do so, you must flush the SpriteBatch by calling end() at the start of the method. in addition, you should remember to call begin() at the start of the method.

This method provides the correct transformation matrix and tint color. You do not need to worry about whether the node uses relative color. This method is called by render() and these values are guaranteed to be correct. In addition, this method does not need to check for visibility, as it is guaranteed to only be called when the node is visible.

Parameters

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The tint to blend with the Node color.

Reimplemented from cugl::scene2::SceneNode.

Reimplemented in cugl::scene2::TextField.

◆ getBackground()

Color4 cugl::scene2::Label::getBackground ( ) const

inline

Returns the background color of this label.

If this color is not CLEAR (the default color), then the label will have a colored backing rectangle. The rectangle will extended from the origin to the content size in Node space.

Returns: the background color of this label.

◆ getBaseLine()

float cugl::scene2::Label::getBaseLine ( ) const

Returns the position of the baseline with respect to the Node origin

The baseline does not necessarily align with the bottom of the text bounds, as letters may overhang.

Returns: the position of the baseline with respect to the Node origin

◆ getBlendEquation()

GLenum cugl::scene2::Label::getBlendEquation ( ) const

inline

Returns the blending equation for this textured node

By default this value is GL_FUNC_ADD. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendEquation.xhtml

This blending equation only affects the texture of the current node. It does not affect any children of the node.

Returns: the blending equation for this sprite batch

◆ getDestinationBlendFactor()

GLenum cugl::scene2::Label::getDestinationBlendFactor ( ) const

inline

Returns the destination blending factor

By default this value is GL_ONE_MINUS_SRC_ALPHA. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

This blending factor only affects the texture of the current node. It does not affect any children of the node.

Returns: the destination blending factor

◆ getFont()

std::shared_ptr<Font> cugl::scene2::Label::getFont ( ) const

inline

Returns the font to use for this label

Returns: the font to use for this label

◆ getForeground()

Color4 cugl::scene2::Label::getForeground ( ) const

inline

Returns the foreground color of this label.

This color will be applied to the characters themselves. This color is BLACK by default.

Returns: the foreground color of this label.

◆ getHorizontalAlignment()

HAlign cugl::scene2::Label::getHorizontalAlignment ( ) const

inline

Returns the horizontal alignment of the text.

This value represents the relationship between the text and its label. It functions as a sort of anchor.

Returns: the horizontal alignment of the text.

◆ getPadding()

const Vec2 cugl::scene2::Label::getPadding ( ) const

inline

Returns the padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has horizontal alignment LEFT and vertical alignment BOTTOM, the padding will shift the text right and up in the label. On the other hand, if it has horizontal alignment RIGHT and vertical alignment TOP, then it will shift the text left and down.

If the horizontal alignment is CENTER or TRUECENTER, then the x padding will be ignored. Similarly, if the vertical alignment is MIDDLE or TRUEMIDDLE, then the y padding will be ignored.

Returns: the padding of the rendered text.

◆ getPaddingX()

float cugl::scene2::Label::getPaddingX ( ) const

inline

Returns the x-axis padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has alignment LEFT and, the padding will shift the text right in the label. On the other hand, if it has alignment RIGHT, then it will shift the text left.

If the alignment is CENTER or TRUECENTER, then the padding will be ignored.

Returns: the x-axis padding of the rendered text.

◆ getPaddingY()

float cugl::scene2::Label::getPaddingY ( ) const

inline

Returns the y-axis padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has BOTTOM, the padding will shift the text up in the label. On the other hand, if it has alignment TOP, then it will shift the text down.

If the alignment is MIDDLE or TRUEMIDDLE, then the padding will be ignored.

Returns: the y-axis padding of the rendered text.

◆ getSourceBlendFactor()

GLenum cugl::scene2::Label::getSourceBlendFactor ( ) const

inline

Returns the source blending factor

By default this value is GL_SRC_ALPHA. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

This blending factor only affects the texture of the current node. It does not affect any children of the node.

Returns: the source blending factor

◆ getText()

const std::string& cugl::scene2::Label::getText ( ) const

inline

Returns the text for this label.

The string will be in either ASCII or UTF8 format. As all ASCII strings are also UTF8, you can assume that the text is UTF8.

If the font is missing glyphs in this string, the characters in the text may be different than those displayed.

Returns: the text for this label.

◆ getTextBounds()

const Rect cugl::scene2::Label::getTextBounds ( ) const

inline

Returns the bounds of the rendered text.

This is the bounds of the rendered text with respect to the Node space. The size of the bounding box is the minimum size to render the text. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

The origin of the bounds is determined by the padding and the alignment.

If this rectangle extends outside the bounding box of the label (e.g. the rectangle with origin (0,0) and the content size), then only the part of the rectangle inside the bounding box will be rendered.

Returns: the bounds of the rendered text.

◆ getTrueBounds()

const Rect cugl::scene2::Label::getTrueBounds ( ) const

inline

Returns the tightest bounds of the rendered text.

This is the bounds of the rendered text, with respect to the Node space. The size of the bounding box ignores any nautural spacing around the characters. Hence the height is ascent of the tallest character plus the descent of the character with the lowest overhang. The width is that of the characters, ignoring the advance.

The origin of the bounds is determined by the padding and the alignment.

If this rectangle extends outside the bounding box of the label (e.g. the rectangle with origin (0,0) and the content size), then only the part of the rectangle inside the bounding box will be rendered.

Returns: the bounds of the rendered text.

◆ getVerticalAlignment()

VAlign cugl::scene2::Label::getVerticalAlignment ( ) const

inline

Returns the horizontal alignment of the text.

This value represents the relationship between the text and its label. It functions as a sort of anchor.

Returns: the horizontal alignment of the text.

◆ init() [1/2]

virtual bool cugl::scene2::Label::init ( )

inlineoverridevirtual

Deactivates the default initializer.

This initializer may not be used for a label. A label must have a font.

Returns: false

Reimplemented from cugl::scene2::SceneNode.

◆ init() [2/2]

bool cugl::scene2::Label::init	(	const Size	size,
		const std::shared_ptr< Font > &	font
	)

Initializes a label with the given size and font

The text is empty and may be set later with setText().

Parameters

size	The size of the label to display
font	The font for this label

Returns: true if initialization was successful.

◆ initWithData()

virtual bool cugl::scene2::Label::initWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

overridevirtual

Initializes a node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "font":         The name of a previously loaded font asset
 "text":         The initial label text
 "foreground":   A four-element integer array. Values should be 0..255
 "background":   A four-element integer array. Values should be 0..255
 "padding":      A two-element float array.
 "halign":       One of 'left', 'center', 'right', 'hard left',
                 'true center' and 'hard right'.
 "valign":       One of 'top', 'middle', 'bottom', 'hard top',
                 'true middle' and 'hard bottom'.

The attribute 'font' is REQUIRED. All other attributes are optional.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithText() [1/2]

bool cugl::scene2::Label::initWithText	(	const char *	text,
		const std::shared_ptr< Font > &	font
	)

inline

Initializes a label with the given text and font

The label will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

All unprintable characters will be removed from the string. This includes tabs and newlines. They will be replaced by spaces. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters

text	The text to display in the label
font	The font for this label

Returns: true if initialization was successful.

◆ initWithText() [2/2]

bool cugl::scene2::Label::initWithText	(	const std::string &	text,
		const std::shared_ptr< Font > &	font
	)

Initializes a label with the given text and font

The label will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

All unprintable characters will be removed from the string. This includes tabs and newlines. They will be replaced by spaces. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters

text	The text to display in the label
font	The font for this label

Returns: true if initialization was successful.

◆ setBackground()

void cugl::scene2::Label::setBackground ( Color4 color )

Sets the background color of this label.

If this color is not CLEAR (the default color), then the label will have a colored backing rectangle. The rectangle will extended from the origin to the content size in Node space.

Parameters

color The background color of this label.

◆ setBlendEquation()

void cugl::scene2::Label::setBlendEquation ( GLenum equation )

inline

Sets the blending equation for this textured node

The enum must be a standard ones supported by OpenGL. See

 https://www.opengl.org/sdk/docs/man/html/glBlendEquation.xhtml

However, this setter does not do any error checking to verify that the input is valid. By default, the equation is GL_FUNC_ADD.

This blending equation only affects the texture of the current node. It does not affect any children of the node.

Parameters

equation Specifies how source and destination colors are combined

◆ setBlendFunc()

void cugl::scene2::Label::setBlendFunc	(	GLenum	srcFactor,
		GLenum	dstFactor
	)

inline

Sets the blending function for this texture node.

The enums are the standard ones supported by OpenGL. See

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

However, this setter does not do any error checking to verify that the enums are valid. By default, srcFactor is GL_SRC_ALPHA while dstFactor is GL_ONE_MINUS_SRC_ALPHA. This corresponds to non-premultiplied alpha blending.

This blending factor only affects the texture of the current node. It does not affect any children of the node.

Parameters

srcFactor	Specifies how the source blending factors are computed
dstFactor	Specifies how the destination blending factors are computed.

◆ setContentSize() [1/2]

virtual void cugl::scene2::Label::setContentSize ( const Size size )

overridevirtual

Sets the untransformed size of the node.

The content size remains the same no matter how the node is scaled or rotated. All nodes must have a size, though it may be degenerate (0,0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

In addition, if the rendered text is less than the content size, it may be cut off in rendering.

Parameters

size	The untransformed size of the node.

Reimplemented from cugl::scene2::SceneNode.

◆ setContentSize() [2/2]

virtual void cugl::scene2::Label::setContentSize	(	float	width,
		float	height
	)

inlineoverridevirtual

Sets the untransformed size of the node.

The content size remains the same no matter how the node is scaled or rotated. All nodes must have a size, though it may be degenerate (0,0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

Parameters

width	The untransformed width of the node.
height	The untransformed height of the node.

Reimplemented from cugl::scene2::SceneNode.

◆ setFont()

void cugl::scene2::Label::setFont	(	const std::shared_ptr< Font > &	font,
		bool	resize = `false`
	)

Sets the font to use this label

Changing this value will regenerate the render data, and is potentially expensive, particularly if the font does not have an atlas.

Parameters

font	The font to use for this label
resize	Whether to resize this label to fit the new font

◆ setForeground()

void cugl::scene2::Label::setForeground ( Color4 color )

inline

Sets the foreground color of this label.

This color will be applied to the characters themselves. This color is BLACK by default.

Parameters

color The foreground color of this label.

◆ setHorizontalAlignment()

void cugl::scene2::Label::setHorizontalAlignment ( HAlign halign )

Sets the horizontal alignment of the text.

This value represents the relationship between the text and its label. It functions as a sort of anchor.

Parameters

halign The horizontal alignment of the text.

◆ setPadding() [1/2]

void cugl::scene2::Label::setPadding ( const Vec2 padding )

inline

Sets the padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has horizontal alignment LEFT and vertical alignment BOTTOM, the padding will shift the text right and up in the label. On the other hand, if it has horizontal alignment RIGHT and vertical alignment TOP, then it will shift the text left and down.

If the horizontal alignment is CENTER or TRUECENTER, then the x padding will be ignored. Similarly, if the vertical alignment is MIDDLE or TRUEMIDDLE, then the y padding will be ignored.

Parameters

padding The padding of the rendered text.

◆ setPadding() [2/2]

void cugl::scene2::Label::setPadding	(	float	padx,
		float	pady
	)

Sets the padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has horizontal alignment LEFT and vertical alignment BOTTOM, the padding will shift the text right and up in the label. On the other hand, if it has horizontal alignment RIGHT and vertical alignment TOP, then it will shift the text left and down.

If the horizontal alignment is CENTER or TRUECENTER, then the x padding will be ignored. Similarly, if the vertical alignment is MIDDLE or TRUEMIDDLE, then the y padding will be ignored.

Parameters

padx	The x-axis padding of the rendered text.
pady	The y-axis padding of the rendered text.

◆ setPaddingX()

void cugl::scene2::Label::setPaddingX ( float padx )

inline

Sets the x-axis padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has alignment LEFT and, the padding will shift the text right in the label. On the other hand, if it has alignment RIGHT, then it will shift the text left.

If the alignment is CENTER or TRUECENTER, then the padding will be ignored.

Parameters

padx	The x-axis padding of the rendered text.

◆ setPaddingY()

void cugl::scene2::Label::setPaddingY ( float pady )

inline

Sets the y-axis padding of the rendered text.

The application of padding depends on how the text is aligned in the label. For example, if the text has BOTTOM, the padding will shift the text up in the label. On the other hand, if it has alignment TOP, then it will shift the text down.

If the alignment is MIDDLE or TRUEMIDDLE, then the padding will be ignored.

Parameters

pady	The y-axis padding of the rendered text.

◆ setText()

virtual void cugl::scene2::Label::setText	(	const std::string &	text,
		bool	resize = `false`
	)

virtual

Sets the text for this label.

All unprintable characters will be removed from the string. This includes tabs and newlines. They will be replaced by spaces.

The string must be in either ASCII or UTF8 format. No other string encodings are supported. As all ASCII strings are also UTF8, you can this effectively means that the text must be UTF8.

If the font is missing glyphs in this string, the characters in the text may be different than those displayed.

Changing this value will regenerate the render data, and is potentially expensive, particularly if the font does not have an atlas.

Parameters

text	The text for this label.
resize	Whether to resize the label to fit the new text.

Reimplemented in cugl::scene2::TextField.

◆ setVerticalAlignment()

void cugl::scene2::Label::setVerticalAlignment ( VAlign valign )

Sets the horizontal alignment of the text.

This value represents the relationship between the text and its label. It functions as a sort of anchor.

Parameters

valign The horizontal alignment of the text.

Member Data Documentation

◆ _background

Color4 cugl::scene2::Label::_background

protected

The color of the background panel (default is CLEAR)

◆ _blendEquation

GLenum cugl::scene2::Label::_blendEquation

protected

The blending equation for this texture

◆ _bounds

Rect cugl::scene2::Label::_bounds

protected

The font bounds

◆ _dstFactor

GLenum cugl::scene2::Label::_dstFactor

protected

The destination factor for the blend function

◆ _font

std::shared_ptr<Font> cugl::scene2::Label::_font

protected

The font (with or without an atlas)

◆ _foreground

Color4 cugl::scene2::Label::_foreground

protected

The color of the text (default is BLACK)

◆ _halign

HAlign cugl::scene2::Label::_halign

protected

The horizontal alignment of the text in this label

◆ _mesh

Mesh<SpriteVertex2> cugl::scene2::Label::_mesh

protected

The glyph vertices

◆ _padding

Vec2 cugl::scene2::Label::_padding

protected

The padding offset

◆ _rendered

bool cugl::scene2::Label::_rendered

protected

Whether or not the glyphs have been rendered

◆ _srcFactor

GLenum cugl::scene2::Label::_srcFactor

protected

The source factor for the blend function

◆ _text

std::string cugl::scene2::Label::_text

protected

The label text

◆ _textbounds

Rect cugl::scene2::Label::_textbounds

protected

The bounds of this rendered text

◆ _texture

std::shared_ptr<Texture> cugl::scene2::Label::_texture

protected

The underlying atlas texture

◆ _truebounds

Rect cugl::scene2::Label::_truebounds

protected

The true bounds of this rendered text, ignoring any natural spacing

◆ _valign

VAlign cugl::scene2::Label::_valign

protected

The vertical alignment of the text in this label

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

include/cugl/scene2/ui/CULabel.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ HAlign

◆ VAlign

Constructor & Destructor Documentation

◆ Label()

◆ ~Label()

Member Function Documentation

◆ alloc() [1/3]

◆ alloc() [2/3]

◆ alloc() [3/3]

◆ allocWithData()

◆ dispose()

◆ draw()

◆ getBackground()

◆ getBaseLine()

◆ getBlendEquation()

◆ getDestinationBlendFactor()

◆ getFont()

◆ getForeground()

◆ getHorizontalAlignment()

◆ getPadding()

◆ getPaddingX()

◆ getPaddingY()

◆ getSourceBlendFactor()

◆ getText()

◆ getTextBounds()

◆ getTrueBounds()

◆ getVerticalAlignment()

◆ init() [1/2]

◆ init() [2/2]

◆ initWithData()

◆ initWithText() [1/2]

◆ initWithText() [2/2]

◆ setBackground()

◆ setBlendEquation()

◆ setBlendFunc()

◆ setContentSize() [1/2]

◆ setContentSize() [2/2]

◆ setFont()

◆ setForeground()

◆ setHorizontalAlignment()

◆ setPadding() [1/2]

◆ setPadding() [2/2]

◆ setPaddingX()

◆ setPaddingY()

◆ setText()

◆ setVerticalAlignment()

Member Data Documentation

◆ _background

◆ _blendEquation

◆ _bounds

◆ _dstFactor

◆ _font

◆ _foreground

◆ _halign

◆ _mesh

◆ _padding

◆ _rendered

◆ _srcFactor

◆ _text

◆ _textbounds

◆ _texture

◆ _truebounds

◆ _valign