CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::scene2::Label Class Reference

#include <CULabel.h>

Inheritance diagram for cugl::scene2::Label:
cugl::scene2::SceneNode cugl::scene2::TextField

Public Member Functions

 Label ()
 
 ~Label ()
 
virtual void dispose () override
 
virtual bool initWithPosition (const Vec2 pos) override
 
bool initWithPosition (float x, float y)
 
virtual bool initWithBounds (const Size size) override
 
virtual bool initWithBounds (float width, float height) override
 
virtual bool initWithBounds (const Rect rect) override
 
virtual bool initWithBounds (float x, float y, float width, float height) override
 
bool initWithText (const std::string text, const std::shared_ptr< Font > &font)
 
bool initWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)
 
bool initWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)
 
bool initWithTextBox (const Rect rect, 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)
 
std::shared_ptr< FontgetFont () const
 
void setFont (const std::shared_ptr< Font > &font, bool resize=false)
 
HorizontalAlign getHorizontalAlignment () const
 
void setHorizontalAlignment (HorizontalAlign halign)
 
VerticalAlign getVerticalAlignment () const
 
void setVerticalAlignment (VerticalAlign valign)
 
bool getWrap () const
 
void setWrap (bool wrap)
 
float getSpacing () const
 
void setSpacing (float spacing)
 
void setPadding (float left, float bottom, float right, float top)
 
void setPadding (float pad)
 
float getPaddingLeft () const
 
void setPaddingLeft (float left)
 
float getPaddingBottom () const
 
void setPaddingBottom (float bot)
 
float getPaddingRight () const
 
void setPaddingRight (float right)
 
float getPaddingTop () const
 
void setPaddingTop (float top)
 
const Rect getInterior () const
 
void setInterior (const Rect rect)
 
const Rect getTextBounds () const
 
const Rect getTrueBounds () 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)
 
const Vec2getDropShadow () const
 
void setDropShadow (const Vec2 p)
 
void setDropShadow (float x, float y)
 
float getShadowBlur () const
 
void setShadowBlur (float blur)
 
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 Affine2 &transform, Color4 tint) override
 
- Public Member Functions inherited from cugl::scene2::SceneNode
 SceneNode ()
 
 ~SceneNode ()
 
virtual void dispose ()
 
virtual bool init ()
 
virtual bool initWithPosition (const Vec2 pos)
 
bool initWithPosition (float x, float y)
 
virtual bool initWithBounds (const Size size)
 
virtual bool initWithBounds (float width, float height)
 
virtual bool initWithBounds (const Rect rect)
 
virtual bool initWithBounds (float x, float y, float width, float height)
 
virtual bool initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 
virtual std::shared_ptr< SceneNodecopy (const std::shared_ptr< SceneNode > &dst) const
 
unsigned int getTag () const
 
void setTag (unsigned int tag)
 
const std::string getName () const
 
void setName (const std::string name)
 
const std::string getClassName () const
 
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
 
virtual void setContentSize (const Size size)
 
virtual void setContentSize (float width, float height)
 
float getContentWidth () const
 
void setContentWidth (float width)
 
float getContentHeight () const
 
void setContentHeight (float height)
 
virtual Rect getLayoutBounds () const
 
Size getSize () const
 
float getWidth () const
 
float getHeight () const
 
Rect getBoundingBox () const
 
virtual void setAnchor (const Vec2 anchor)
 
virtual 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 () const
 
void setRelativeColor (bool flag)
 
std::shared_ptr< ScissorgetScissor () 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 Affine2getTransform () const
 
const Affine2getAlternateTransform () const
 
void setAlternateTransform (const Affine2 &transform)
 
bool withAlternateTransform ()
 
void chooseAlternateTransform (bool active)
 
const Affine2getNodeToParentTransform () const
 
Affine2 getParentToNodeTransform () const
 
Affine2 getNodeToWorldTransform () const
 
Affine2 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
 
size_t getChildCount () const
 
std::shared_ptr< SceneNodegetChild (unsigned int pos)
 
const std::shared_ptr< SceneNode > & getChild (unsigned int pos) const
 
template<typename T >
std::shared_ptr< TgetChild (unsigned int pos) const
 
std::shared_ptr< SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< TgetChildByTag (unsigned int tag) const
 
std::shared_ptr< SceneNodegetChildByName (const std::string name) const
 
template<typename T >
std::shared_ptr< TgetChildByName (const std::string name) const
 
std::vector< std::shared_ptr< SceneNode > > getChildren ()
 
const std::vector< std::shared_ptr< SceneNode > > & getChildren () const
 
void addChild (const std::shared_ptr< SceneNode > &child)
 
void addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag)
 
void addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string name)
 
void swapChild (const std::shared_ptr< SceneNode > &child1, const std::shared_ptr< SceneNode > &child2, bool inherit=false)
 
SceneNodegetParent ()
 
const SceneNodegetParent () const
 
Scene2getScene ()
 
const Scene2getScene () 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 ()
 
void setPriority (float priority)
 
float getPriority ()
 
virtual void render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)
 
virtual void render (const std::shared_ptr< SpriteBatch > &batch)
 
virtual void draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)
 
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< LabelallocWithBounds (const Size size)
 
static std::shared_ptr< LabelallocWithBounds (float width, float height)
 
static std::shared_ptr< LabelallocWithBounds (const Rect rect)
 
static std::shared_ptr< LabelallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< LabelallocWithText (const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< SceneNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 
- Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNodealloc ()
 
static std::shared_ptr< SceneNodeallocWithPosition (const Vec2 pos)
 
static std::shared_ptr< SceneNodeallocWithPosition (float x, float y)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Size size)
 
static std::shared_ptr< SceneNodeallocWithBounds (float width, float height)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Rect rect)
 
static std::shared_ptr< SceneNodeallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< SceneNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 

Protected Member Functions

virtual void generateRenderData ()
 
void clearRenderData ()
 
void updateColor ()
 
void resize ()
 
void reanchor ()
 

Protected Attributes

std::shared_ptr< Font_font
 
std::shared_ptr< TextLayout_layout
 
Vec2 _offset
 
float _padbot
 
float _padleft
 
float _padtop
 
float _padrght
 
bool _dropShadow
 
float _dropBlur
 
Vec2 _dropOffset
 
Color4 _foreground
 
Color4 _background
 
GLenum _blendEquation
 
GLenum _srcFactor
 
GLenum _dstFactor
 
bool _rendered
 
Rect _bounds
 
std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > _glyphrun
 
- 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
 
Affine2 _transform
 
bool _useTransform
 
Affine2 _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
 
std::string _classname
 
float _priority
 
std::shared_ptr< JsonValue_json
 

Detailed Description

This class is a node the represents formatted text on rectangular background.

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.

The text itself is formatted using a TextLayout. This text layout breaks the text into multiple lines as needed, though by default, a label only breaks lines at explicit newlines. The text layout aligns the lines of text with each other. But it also positions the text against the background rectangle as well. See getHorizontalAlignment and getVerticalAlignment for more information.

To display the text, you need a Font. The label assumes that the font has an atlas, either through a pre-built atlas, or by setting the attribute Font#setAtlasFallback to true. If the font does not have an atlas, or characters are missing from the atlas, then those glyphs will not be displayed. It is generally recommended that you use a prebuilt atlas, as fallback atlases introduce significant time and memory overhead.

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

◆ allocWithBounds() [1/4]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithBounds ( const Rect  rect)
inlinestatic

Returns a newly allocated label with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will empty, as it has no font or text.

Parameters
rectThe bounds of the label in parent space
Returns
a newly allocated label with the given bounds.

◆ allocWithBounds() [2/4]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithBounds ( const Size  size)
inlinestatic

Returns a newly allocated label with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will empty, as it has no font or text.

Parameters
sizeThe size of the label in parent space
Returns
a newly allocated label with the given size.

◆ allocWithBounds() [3/4]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithBounds ( float  width,
float  height 
)
inlinestatic

Returns a newly allocated label with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will empty, as it has no font or text.

Parameters
widthThe width of the label in parent space
heightThe height of the label in parent space
Returns
a newly allocated label with the given size.

◆ allocWithBounds() [4/4]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithBounds ( float  x,
float  y,
float  width,
float  height 
)
inlinestatic

Returns a newly allocated label with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will empty, as it has no font or text.

Parameters
xThe x-coordinate of the label origin in parent space
yThe y-coordinate of the label origin in parent space
widthThe width of the label in parent space
heightThe height of the label in parent space
Returns
a newly allocated label with the given bounds.

◆ 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": Either a four-element integer array (values 0..255) or a string.
              Any string should be a web color or a Tkinter color name.
"background": Either a four-element integer array (values 0..255) or a string.
              Any string should be a web color or a Tkinter color name.
"padding":    A number or a 4-element float array.
"dropshadow": A boolean indicating the presence of a drop shadow
"wrap":       A boolean indicating whether to break text into lines
"spacing":    A float indicating the spacing factor between lines
"halign":     One of 'left', 'center', 'right', 'justify', 'hard left',
              'true center' and 'hard right'.
"valign":     One of 'top', 'middle', 'bottom', 'hard top', 'true middle'
              and 'hard bottom'.

All attributes are optional. There are no required attributes. However, a label without a font cannot display text.

Parameters
loaderThe scene loader passing this JSON file
dataThe JSON object specifying the node
Returns
a newly allocated node with the given JSON specificaton.

◆ allocWithText() [1/2]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithText ( 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.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters
textThe text to display in the label
fontThe font for this label
Returns
a newly allocated label with the given text and font atlas

◆ allocWithText() [2/2]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithText ( const Vec2  position,
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.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters
positionThe label position
textThe text to display in the label
fontThe font for this label
Returns
a newly allocated label with the given text and font atlas

◆ allocWithTextBox() [1/2]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithTextBox ( const Rect  rect,
const std::string  text,
const std::shared_ptr< Font > &  font 
)
inlinestatic

Returns a newly allocated multiline label with the given dimensions

The label will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline label is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will use the rectangle origin to position this label in its parent. It will be anchored in the bottom left.

Parameters
rectThe bounds of the label to display
textThe text to display in the label
fontThe font for this label
Returns
a newly allocated multiline label with the given dimensions

◆ allocWithTextBox() [2/2]

static std::shared_ptr< Label > cugl::scene2::Label::allocWithTextBox ( const Size  size,
const std::string  text,
const std::shared_ptr< Font > &  font 
)
inlinestatic

Returns a newly allocated multiline label with the given dimensions

The label will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline label is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will be placed at the origin of the parent and will be anchored in the bottom left.

Parameters
sizeThe size of the label to display
textThe text to display in the label
fontThe font for this label
Returns
a newly allocated multiline label with the given dimensions

◆ clearRenderData()

void cugl::scene2::Label::clearRenderData ( )
protected

Clears the render data, releasing all vertices and indices.

◆ 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 Affine2 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
batchThe SpriteBatch to draw with.
transformThe global transformation matrix.
tintThe tint to blend with the Node color.

Reimplemented from cugl::scene2::SceneNode.

Reimplemented in cugl::scene2::TextField.

◆ generateRenderData()

virtual void cugl::scene2::Label::generateRenderData ( )
protectedvirtual

Allocates the render data necessary to render this node.

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.

◆ 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

◆ getDropShadow()

const Vec2 & cugl::scene2::Label::getDropShadow ( ) const
inline

Returns the drop shadow offset of this label

A drop shadow is a blurred and/or slightly offset version of the label text, drawn behind the original text. The color of the drop shadow is always a slighlty transparent black. It is used to give a sense of depth to the text.

This property controls the offset of the drop shadow but does not control the blur. You must use the property getShadowBlur for that. A typical drop shadow is offset down and to the right with minor blurring.

Returns
the drop shadow offset of this label

◆ 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()

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

Returns the horizontal alignment of the text.

Horizontal alignment serves two purposes in a label. First it is the alignment of multiple lines of text to each other, as specified in TextLayout. But it also represents the relationship between the text and the background region of this node. In particular, setting this value has the following effects:

LEFT, HARD_LEFT, and JUSTIFY all place the left edge of the text layout against the left edge of the label, after applying padding. Similarly, RIGHT places the right edge of the text layout against the right edge of the label, after applying padding.

Padding is unusual for the CENTER and TRUE_CENTER alignments. The center of the label is determined from the edges after applying padding. So if the left and right padding are not equal, then the text will not be placed at the true center. Even if they are equal, the left and right padding reduce the width of the label, which can affect word wrap.

This value is LEFT by default.

Returns
the horizontal alignment of the text.

◆ getInterior()

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

Returns the non-padded interior of this label.

Padding can be added to the bottom, left, top, and right edges of the label. This padding detracts from the area in which text can appear, and can influence the word wrap. We call the area of the label in which the text can appear the interior of the label.

Normally the content bounds of a scene graph node has origin (0,0) and size SceneNode#getContentSize. This method shifts the origin and reduces the width and height to account for the padding on the edges.

Returns
the non-padded interior of this label.

◆ getPaddingBottom()

float cugl::scene2::Label::getPaddingBottom ( ) const
inline

Returns the bottom-edge padding of the label.

Adding bottom padding to a label does not effect word wrap, but it can affect the text position. If the text has alignment BOTTOM or BASELINE, the label will shift the text up by this amount. On the other hand, it will have no effect on TOP aligned text.

For MIDDLE aligned text, the label middle is computed after applying padding to the edges. So the top and bottom padding should be equal to ensure that the text is in the true middle of the label.

Returns
the bottom-edge padding of the label.

◆ getPaddingLeft()

float cugl::scene2::Label::getPaddingLeft ( ) const
inline

Returns the left-edge padding of the label.

Adding left padding to a label reduces the text width of the label, which can affect word wrap (if enabled). In addition, the padding can affect the position of the text. If the text has alignment LEFT or JUSTIFY, the label will shift the text right by this amount. On the other hand, it will have no effect on RIGHT aligned text (other than reducing the line width).

For CENTER aligned text, the label center is computed after applying padding to the edges. So the left and right padding should be equal to ensure that the text is in the true center of the label.

Returns
the left-edge padding of the label.

◆ getPaddingRight()

float cugl::scene2::Label::getPaddingRight ( ) const
inline

Returns the right-edge padding of the label.

Adding right padding to a label reduces the text width of the label, which can affect word wrap (if enabled). In addition, the padding can affect the position of the text. If the text has alignment RIGHT then the label will shift the text left by this amount. On the other hand, it will have no effect on LEFT or JUSTIFY aligned text (other than reducing the line width).

For CENTER aligned text, the label center is computed after applying padding to the edges. So the left and right padding should be equal to ensure that the text is in the true center of the label.

Returns
the right-edge padding of the label.

◆ getPaddingTop()

float cugl::scene2::Label::getPaddingTop ( ) const
inline

Returns the top-edge padding of the label.

Adding top padding to a label does not effect word wrap, but it can affect the position of the text. If the text has alignment TOP, the label will shift the text down by this amount. On the other hand, it will have no effect on BOTTOM or BASELINE aligned text.

For MIDDLE aligned text, the label middle is computed after applying padding to the edges. So the top and bottom padding should be equal to ensure that the text is in the true middle of the label.

Returns
the top-edge padding of the label.

◆ getShadowBlur()

float cugl::scene2::Label::getShadowBlur ( ) const
inline

Returns the drop shadow blur of this label

A drop shadow is a blurred and/or slightly offset version of the label text, drawn behind the original text. The color of the drop shadow is always a slighlty transparent black. It is used to give a sense of depth to the text.

This property controls the offset of the drop shadow but does not control the blur. You must use the property getShadowBlur for that. A typical drop shadow is offset down and to the right with minor blurring.

When blurring a drop shadow, remember to use a font with the same Font#getPadding as the blur size. This will prevent bleeding across characters in the atlas.

Returns
the drop shadow blur of this label

◆ 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

◆ getSpacing()

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

Returns the line spacing of this label.

This value is multiplied by the font size to determine the space between lines in the label. So a value of 1 is single-spaced text, while a value of 2 is double spaced. The value should be positive.

Returns
the line spacing of this label.

◆ getText()

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

Returns the text for this label.

The string will 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. Furthermore, if this label has no font, then the text will not display at all.

Returns
the text for this label.

◆ getTextBounds()

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

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 natural size to render the text. This corresponds to TextLayout#getBounds of the underlying text layout. In particular, this means there may be some natural spacing around the characters.

The origin of the bounds is determined by the padding and 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

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. It also includes any tracking applied to each line. This corresponds to TextLayout#getTrueBounds of the underlying text layout.

The origin of the bounds is determined by the padding and 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 tightest bounds of the rendered text.

◆ getVerticalAlignment()

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

Returns the vertical alignment of the text.

Vertical alignment is used to place the formatted text in against the background rectangle. The options are interpretted as follows:

TOP and HARD_TOP place the top edge of the text layout against the top edge of the label, after applying padding. Note that the meaning of "top edge" differs between TOP and HARD_TOP in TextLayout. Similarly, BOTTOM and HARD_BOTTOM place the bottom edge of the text layout against the bottom edge of the label, after applying padding.

Padding is unusual for the MIDDLE and TRUE_MIDDLE alignments. The middle of the label is determined from the edges after applying padding. So if the top and bottom padding are not equal, then the text will not be placed at the true middle.

Finally, for BASELINE, this will place the baseline of the bottom line (not the top, as the case with TextLayout) line at the bottom edge of the label, after adjusting for padding.

This value is TOP by default.

Returns
the vertical alignment of the text.

◆ getWrap()

bool cugl::scene2::Label::getWrap ( ) const

Returns true if this label will wrap text to fit.

By default, label text will be displayed on one line (unless it has newline characters). This could cause the text to exceed the bounds of the content size and be cut off. If this option is true, the label will break up lines at white space locations (or mid-word if there are no white space locations) so that each line can fit in the width of the content region. This could still cause text to be cut off if the height of the content region is not large enough.

Not that even if this value is false, a label will still break lines at newline characters. If you do not want the label to break up a string with newlines, you should remove the newline characters from the string (as these are not renderable anyway).

Returns
true if this label will wrap text to fit.

◆ initWithBounds() [1/4]

virtual bool cugl::scene2::Label::initWithBounds ( const Rect  rect)
overridevirtual

Initializes a node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will be empty, as it has no font or text.

Parameters
rectThe bounds of the node in parent space
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [2/4]

virtual bool cugl::scene2::Label::initWithBounds ( const Size  size)
overridevirtual

Initializes a label with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will be empty, as it has no font or text.

Parameters
sizeThe size of the node in parent space
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [3/4]

virtual bool cugl::scene2::Label::initWithBounds ( float  width,
float  height 
)
inlineoverridevirtual

Initializes a node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will be empty, as it has no font or text.

Parameters
widthThe width of the node in parent space
heightThe height of the node in parent space
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [4/4]

virtual bool cugl::scene2::Label::initWithBounds ( float  x,
float  y,
float  width,
float  height 
)
inlineoverridevirtual

Initializes a node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will be empty, as it has no font or text.

Parameters
xThe x-coordinate of the node origin in parent space
yThe y-coordinate of the node origin in parent space
widthThe width of the node in parent space
heightThe height of the node in parent space
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ 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": Either a four-element integer array (values 0..255) or a string.
              Any string should be a web color or a Tkinter color name.
"background": Either a four-element integer array (values 0..255) or a string.
              Any string should be a web color or a Tkinter color name.
"padding":    A number or a 4-element float array.
"dropshadow": A boolean indicating the presence of a drop shadow
"wrap":       A boolean indicating whether to break text into lines
"spacing":    A float indicating the spacing factor between lines
"halign":     One of 'left', 'center', 'right', 'justify', 'hard left',
              'true center' and 'hard right'.
"valign":     One of 'top', 'middle', 'bottom', 'hard top', 'true middle'
              and 'hard bottom'.

All attributes are optional. There are no required attributes. However, a label without a font cannot display text.

Parameters
loaderThe scene loader passing this JSON file
dataThe JSON object specifying the node
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

Reimplemented in cugl::scene2::TextField.

◆ initWithPosition() [1/2]

virtual bool cugl::scene2::Label::initWithPosition ( const Vec2  pos)
inlineoverridevirtual

Disables the inherited initializer.

This initializer is disabled and should not be used.

Returns
false

Reimplemented from cugl::scene2::SceneNode.

◆ initWithPosition() [2/2]

bool cugl::scene2::Label::initWithPosition ( float  x,
float  y 
)
inline

Disables the inherited initializer.

This initializer is disabled and should not be used.

Returns
false

◆ initWithText() [1/2]

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

Initializes a label at (0,0) 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.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters
textThe text to display in the label
fontThe font for this label
Returns
true if initialization was successful.

◆ initWithText() [2/2]

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

Initializes a label at the position 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.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

Parameters
positionThe label position
textThe text to display in the label
fontThe font for this label
Returns
true if initialization was successful.

◆ initWithTextBox() [1/2]

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

Initializes a multiline label with the given dimensions

The label will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline label is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will use the rectangle origin to position this label in its parent. It will be anchored in the bottom left.

Parameters
rectThe bounds of the label to display
textThe text to display in the label
fontThe font for this label
Returns
true if initialization was successful.

◆ initWithTextBox() [2/2]

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

Initializes a multiline label with the given dimensions

The label will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline label is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will be placed at the origin of the parent and will be anchored in the bottom left.

Parameters
sizeThe size of the label to display
textThe text to display in the label
fontThe font for this label
Returns
true if initialization was successful.

◆ reanchor()

void cugl::scene2::Label::reanchor ( )
protected

Repositions the text inside of this label.

This method is called whenever there is a formatting or alignment change to the label.

◆ resize()

void cugl::scene2::Label::resize ( )
protected

Resizes the content bounds to fit the text.

◆ 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
colorThe 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
equationSpecifies 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
srcFactorSpecifies how the source blending factors are computed
dstFactorSpecifies 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 cannot fit in the content size, it may be cut off in rendering.

Parameters
sizeThe 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.

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

Parameters
widthThe untransformed width of the node.
heightThe untransformed height of the node.

Reimplemented from cugl::scene2::SceneNode.

◆ setDropShadow() [1/2]

void cugl::scene2::Label::setDropShadow ( const Vec2  p)
inline

Sets the drop shadow offset of this label

A drop shadow is a blurred and/or slightly offset version of the label text, drawn behind the original text. The color of the drop shadow is always a slighlty transparent black. It is used to give a sense of depth to the text.

This property controls the offset of the drop shadow but does not control the blur. You must use the property getShadowBlur for that. A typical drop shadow is offset down and to the right with minor blurring.

Parameters
pThe drop shadow offset of this label

◆ setDropShadow() [2/2]

void cugl::scene2::Label::setDropShadow ( float  x,
float  y 
)

Sets the drop shadow offset of this label

A drop shadow is a blurred and/or slightly offset version of the label text, drawn behind the original text. The color of the drop shadow is always a slighlty transparent black. It is used to give a sense of depth to the text.

This property controls the offset of the drop shadow but does not control the blur. You must use the property getShadowBlur for that. A typical drop shadow is offset down and to the right with minor blurring.

Parameters
xThe x-offset of the drop shadow
yThe x-offset of the drop shadow

◆ 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
fontThe font to use for this label
resizeWhether 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
colorThe foreground color of this label.

◆ setHorizontalAlignment()

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

Sets the horizontal alignment of the text.

Horizontal alignment serves two purposes in a label. First it is the alignment of multiple lines of text to each other, as specified in TextLayout. But it also represents the relationship between the text and the background region of this node. In particular, setting this value has the following effects:

LEFT, HARD_LEFT, and JUSTIFY all place the left edge of the text layout against the left edge of the label, after applying padding. Note that the meaning of the "left edge" differs between LEFT and HARD_LEFT in TextLayout. Similarly, RIGHT and HARD_RIGHT place the right edge of the text layout against the right edge of the label, after applying padding.

Padding is unusual for the CENTER and TRUE_CENTER alignments. The center of the label is determined from the edges after applying padding. So if the left and right padding are not equal, then the text will not be placed at the true center. Even if they are equal, the left and right padding reduce the width of the label, which can affect word wrap.

This value is LEFT by default.

Parameters
halignThe horizontal alignment of the text.

◆ setInterior()

void cugl::scene2::Label::setInterior ( const Rect  rect)

Sets the non-padded interior of this label.

Padding can be added to the bottom, left, top, and right edges of the label. This padding detracts from the area in which text can appear, and can influence the word wrap. We call the area of the label in which the text can appear the interior of the label.

This method is essentially an alternate way to set the padding. The method will add padding so that the interior appears in a region with origin (0,0) and size SceneNode#getContentSize. If the interior cannot fit in this region, then the interior will be the intersection. This method will never change the content size of the label.

Parameters
rectThe non-padded interior of this label.

◆ setPadding() [1/2]

void cugl::scene2::Label::setPadding ( float  left,
float  bottom,
float  right,
float  top 
)

Sets the padding of the label.

Padding can be added to the bottom, left, top, and right edges of the label. This padding detracts from the area in which text can appear, and can influence the word wrap. We call the area of the label in which the text can appear the interior of the label.

Padding can also have effect on the various text alignments. See both setHorizontalAlignment and setVerticalAlignment for the affect of padding on alignment.

Parameters
leftThe left edge padding of the label
bottomThe bottom edge padding of the label
rightThe right edge padding of the label
topThe top edge padding of the label

◆ setPadding() [2/2]

void cugl::scene2::Label::setPadding ( float  pad)
inline

Sets the padding of the label.

Padding can be added to the bottom, left, top, and right edges of the label. This padding detracts from the area in which text can appear, and can influence the word wrap. We call the area of the label in which the text can appear the interior of the label. In this method, the padding is applied to uniformly to all sides.

Padding can also have effect on the various text alignments. See both setHorizontalAlignment and setVerticalAlignment for the affect of padding on alignment.

Parameters
padThe uniform padding for each edge

◆ setPaddingBottom()

void cugl::scene2::Label::setPaddingBottom ( float  bot)
inline

Sets the bottom-edge padding of the label.

Adding bottom padding to a label does not effect word wrap, but it can affect the text position. If the text has alignment BOTTOM or BASELINE, the label will shift the text up by this amount. On the other hand, it will have no effect on TOP aligned text.

For MIDDLE aligned text, the label middle is computed after applying padding to the edges. So the top and bottom padding should be equal to ensure that the text is in the true middle of the label.

Parameters
botThe bottom-edge padding of the label.

◆ setPaddingLeft()

void cugl::scene2::Label::setPaddingLeft ( float  left)
inline

Sets the left-edge padding of the label.

Adding left padding to a label reduces the text width of the label, which can affect word wrap (if enabled). In addition, the padding can affect the position of the text. If the text has alignment LEFT or JUSTIFY, the label will shift the text right by this amount. On the other hand, it will have no effect on RIGHT aligned text (other than reducing the line width).

For CENTER aligned text, the label center is computed after applying padding to the edges. So the left and right padding should be equal to ensure that the text is in the true center of the label.

Parameters
leftThe left-edge padding of the label.

◆ setPaddingRight()

void cugl::scene2::Label::setPaddingRight ( float  right)
inline

Sets the right-edge padding of the label.

Adding right padding to a label reduces the text width of the label, which can affect word wrap (if enabled). In addition, the padding can affect the position of the text. If the text has alignment RIGHT then the label will shift the text left by this amount. On the other hand, it will have no effect on LEFT or JUSTIFY aligned text (other than reducing the line width).

For CENTER aligned text, the label center is computed after applying padding to the edges. So the left and right padding should be equal to ensure that the text is in the true center of the label.

Parameters
rightThe right-edge padding of the label.

◆ setPaddingTop()

void cugl::scene2::Label::setPaddingTop ( float  top)
inline

Sets the top-edge padding of the label.

Adding top padding to a label does not effect word wrap, but it can affect the position of the text. If the text has alignment TOP, the label will shift the text down by this amount. On the other hand, it will have no effect on BOTTOM or BASELINE aligned text.

For MIDDLE aligned text, the label middle is computed after applying padding to the edges. So the top and bottom padding should be equal to ensure that the text is in the true middle of the label.

Parameters
topThe top-edge padding of the label.

◆ setShadowBlur()

void cugl::scene2::Label::setShadowBlur ( float  blur)

Sets the drop shadow blur of this label

A drop shadow is a blurred and/or slightly offset version of the label text, drawn behind the original text. The color of the drop shadow is always a slighlty transparent black. It is used to give a sense of depth to the text.

This property controls the offset of the drop shadow but does not control the blur. You must use the property getShadowBlur for that. A typical drop shadow is offset down and to the right with minor blurring.

When blurring a drop shadow, remember to use a font with the same Font#getPadding as the blur size. This will prevent bleeding across characters in the atlas.

Parameters
blurThe drop shadow blur of this label

◆ setSpacing()

void cugl::scene2::Label::setSpacing ( float  spacing)

Sets the line spacing of this label.

This value is multiplied by the font size to determine the space between lines in the label. So a value of 1 is single-spaced text, while a value of 2 is double spaced. The value should be positive.

Parameters
spacingThe line spacing of this label.

◆ setText()

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

Sets the text for this label.

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. Furthermore, if this label has no font, then the text will not display at all.

Changing this value will regenerate the render data, and is potentially expensive, particularly if the font is using a fallback atlas.

Parameters
textThe text for this label.
resizeWhether to resize the label to fit the new text.

Reimplemented in cugl::scene2::TextField.

◆ setVerticalAlignment()

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

Sets the vertical alignment of the text.

Vertical alignment is used to place the formatted text in against the background rectangle. The options are interpretted as follows:

TOP and HARD_TOP place the top edge of the text layout against the top edge of the label, after applying padding. Note that the meaning of "top edge" differs between TOP and HARD_TOP in TextLayout. Similarly, BOTTOM and HARD_BOTTOM place the bottom edge of the text layout against the bottom edge of the label, after applying padding.

Padding is unusual for the MIDDLE and TRUE_MIDDLE alignments. The middle of the label is determined from the edges after applying padding. So if the top and bottom padding are not equal, then the text will not be placed at the true middle.

Finally, for BASELINE, this will place the baseline of the bottom line (not the top, as the case with TextLayout) line at the bottom edge of the label, after adjusting for padding.

This value is TOP by default.

Parameters
valignThe horizontal alignment of the text.

◆ setWrap()

void cugl::scene2::Label::setWrap ( bool  wrap)

Sets whether this label will wrap text to fit.

By default, label text will be displayed on one line (unless it has newline characters). This could cause the text to exceed the bounds of the content size and be cut off. If this option is true, the label will break up lines at white space locations (or mid-word if there are no white space locations) so that each line can fit in the width of the content region. This could still cause text to be cut off if the height of the content region is not large enough.

Not that even if this value is false, a label will still break lines at newline characters. If you do not want the label to break up a string with newlines, you should remove the newline characters from the string (as these are not renderable anyway).

Parameters
wrapWhether this label will wrap text to fit.

◆ updateColor()

void cugl::scene2::Label::updateColor ( )
protected

Updates the color value for any other data that needs it.

This method is used to synchronize the background and foreground colors.

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

◆ _dropBlur

float cugl::scene2::Label::_dropBlur
protected

The blurring effect for the drop shadow

◆ _dropOffset

Vec2 cugl::scene2::Label::_dropOffset
protected

The drop shadow offset

◆ _dropShadow

bool cugl::scene2::Label::_dropShadow
protected

Whether to shadow the text

◆ _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)

◆ _glyphrun

std::unordered_map<GLuint, std::shared_ptr<GlyphRun> > cugl::scene2::Label::_glyphrun
protected

The glyph runs to render

◆ _layout

std::shared_ptr<TextLayout> cugl::scene2::Label::_layout
protected

The underlying text layout (the text and font are accessed from here)

◆ _offset

Vec2 cugl::scene2::Label::_offset
protected

The position to place the origin of the layout (in Node coordinates)

◆ _padbot

float cugl::scene2::Label::_padbot
protected

The bottom padding offset

◆ _padleft

float cugl::scene2::Label::_padleft
protected

The left padding offset

◆ _padrght

float cugl::scene2::Label::_padrght
protected

The right padding offset

◆ _padtop

float cugl::scene2::Label::_padtop
protected

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


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