Axmol 3.0.0-89d6d9a
Loading...
Searching...
No Matches
Label Class Reference

Label is a subclass of Node that knows how to render text labels. More...

#include <Label.h>

Inherits Node.

Public Types

enum class  Overflow { }

Public Member Functions

void setString (std::string_view text) override
 Sets the text that this Label is to display.
std::string_view getString () const override
 Return the text the Label is currently displaying.
int getLineCount () const
 Return the number of lines of text.
int getCharCount () const
 Returns the number of UTF-32 characters.
bool isEmpty () const
 Return whether the text is empty.
virtual void setTextColor (const Color32 &color)
 Sets the text color of Label.
const Color32 & getTextColor () const
 Returns the text color of the Label.
virtual void enableShadow (const Color32 &shadowColor=Color32::black, const Vec2 &offset=Vec2(2, -2), int blurRadius=0)
 Enable shadow effect to Label.
virtual void enableOutline (const Color32 &outlineColor, float outlineSize=-1)
 Enable outline effect to Label.
virtual void enableGlow (const Color32 &glowColor, float glowRadius=-1)
 Enable glow effect to Label.
void enableItalics ()
 Enable italics rendering.
void enableBold ()
 Enable bold rendering.
void enableUnderline ()
 Enable underline.
void enableStrikethrough ()
 Enables strikethrough.
virtual void disableEffect ()
 Disable all effect applied to Label.
virtual void disableEffect (LabelEffect effect)
 Disable effect to Label.
bool isShadowEnabled () const
 Return whether the shadow effect is enabled.
Vec2 getShadowOffset () const
 Return shadow effect offset value.
float getShadowBlurRadius () const
 Return the shadow effect blur radius.
Color getShadowColor () const
 Return the shadow effect color value.
float getOutlineSize () const
 Return the outline effect size value.
LabelEffect getLabelEffectType () const
 Return current effect type.
Color getEffectColor () const
 Return current effect color value.
void setAlignment (TextHAlignment hAlignment)
 Sets the Label's text horizontal alignment.
TextHAlignment getTextAlignment () const
 Returns the Label's text horizontal alignment.
void setAlignment (TextHAlignment hAlignment, TextVAlignment vAlignment)
 Sets the Label's text alignment.
void setHorizontalAlignment (TextHAlignment hAlignment)
 Sets the Label's text horizontal alignment.
TextHAlignment getHorizontalAlignment () const
 Returns the Label's text horizontal alignment.
void setVerticalAlignment (TextVAlignment vAlignment)
 Sets the Label's text vertical alignment.
TextVAlignment getVerticalAlignment () const
 Returns the Label's text vertical alignment.
void setLineBreakWithoutSpace (bool breakWithoutSpace)
 Specify what happens when a line is too long for Label.
void setMaxLineWidth (float maxLineWidth)
 Makes the Label at most this line untransformed width.
void setTTFFaceSize (int faceSize)
 Set the ttf/ttc font face size to determine how big to generate SDF bitmap since axmol-2.1.0.
int getTTFFaceSize () const
 Gets ttf/ttc font face size, since axmol-2.1.0.
void setBMFontSize (float fontSize)
 Change font size of label type BMFONT Note: This function only scale the BMFONT letter to mimic the font size change effect.
float getBMFontSize () const
 Return the user define BMFont size.
void enableWrap (bool enable)
 Toggle wrap option of the label.
bool isWrapEnabled () const
 Query the wrap is enabled or not.
void setOverflow (Overflow overflow)
 Change the label's Overflow type, currently only TTF and BMFont support all the valid Overflow type.
Overflow getOverflow () const
 Query the label's Overflow type.
void setWidth (float width)
 Makes the Label exactly this untransformed width.
void setHeight (float height)
 Makes the Label exactly this untransformed height.
void setDimensions (float width, float height)
 Sets the untransformed size of the Label in a more efficient way.
virtual void updateContent ()
 Update content immediately.
virtual Sprite * getLetter (int lettetIndex)
 Provides a way to treat each character like a Sprite.
void setClipMarginEnabled (bool clipEnabled)
 Clips upper and lower margin to reduce height of Label.
void setLineHeight (float height)
 Sets the line height of the Label.
float getLineHeight () const
 Returns the line height of this Label.
LabelType getLabelType () const
 Returns type of label.
float getRenderingFontSize () const
 Returns font size.
void setAdditionalKerning (float space)
 Sets the additional kerning of the Label.
float getAdditionalKerning () const
 Returns the additional kerning of the Label.
bool setProgramState (rhi::ProgramState *programState, bool ownPS=false) override
 Sets ProgramState with retain.
bool isOpacityModifyRGB () const override
 If node opacity will modify the RGB color value, then you should override this method and return true.
void setOpacityModifyRGB (bool isOpacityModifyRGB) override
 If you want the opacity affect the color property, then set to true.
void updateDisplayedColor (const Color32 &parentColor) override
 Update node's displayed color with its parent color.
void updateDisplayedOpacity (uint8_t parentOpacity) override
 Update the displayed opacity of node with it's parent opacity;.
std::string getDescription () const override
 Gets the description string.
const Vec2 & getContentSize () const override
 Returns the untransformed size of the node.
Rect getBoundingBox () const override
 Returns an AABB (axis-aligned bounding-box) in its parent's coordinate system.
void visit (const SceneRenderState &state, const Mat4 &parentTransform, uint32_t parentFlags) override
 Visits this node's children and draw them recursively.
void draw (const SceneRenderState &state, const Mat4 &transform, uint32_t flags) override
 Override this method to draw your own node.
void setCameraMask (unsigned short mask, bool applyChildren=true) override
 Modify the camera mask for current node.
void removeAllChildrenWithCleanup (bool cleanup) override
 Removes all children from the container, and do a cleanup to all running actions depending on the cleanup parameter.
void removeChild (Node *child, bool cleanup=true) override
 Removes a child from the container.
void setGlobalZOrder (float globalZOrder) override
 Defines the order in which the nodes are renderer.
 Label (TextHAlignment hAlignment=TextHAlignment::LEFT, TextVAlignment vAlignment=TextVAlignment::TOP)
 Constructor of Label.
virtual ~Label ()
 Destructor of Label.
Font methods
void setFontInfo (std::string_view fontName, float fontSize)
 Set font information for the Label.
virtual bool setTTFConfig (const TTFConfig &ttfConfig)
 Sets a new TTF configuration to Label.
virtual const TTFConfig & getTTFConfig () const
 Returns the TTF configuration object used by the Label.
virtual bool setBMFontFilePath (std::string_view bmfontFilePath, float fontSize=0)
 Sets a new bitmap font to Label.
virtual bool setBMFontFilePath (std::string_view bmfontFilePath, const Rect &imageRect, bool imageRotated, float fontSize=0)
 Sets a new bitmap font to Label.
virtual bool setBMFontFilePath (std::string_view bmfontFilePath, std::string_view subTextureKey, float fontSize=0)
 Sets a new bitmap font to Label.
std::string_view getBMFontFilePath () const
 Returns the bitmap font used by the Label.
virtual bool setCharMap (std::string_view charMapFile, int itemWidth, int itemHeight, int startCharMap)
 Sets a new char map configuration to Label.
virtual bool setCharMap (Texture2D *texture, int itemWidth, int itemHeight, int startCharMap)
 Sets a new char map configuration to Label.
virtual bool setCharMap (std::string_view plistFile)
 Sets a new char map configuration to Label.
virtual void setSystemFontName (std::string_view font)
 Sets a new system font to Label.
virtual std::string_view getSystemFontName () const
 Returns the system font used by the Label.
virtual float getSystemFontSize () const
 Returns the bitmap font path used by the Label.
virtual void requestSystemFontRefresh ()
Public Member Functions inherited from Node
virtual bool isRunning () const
 Returns whether or not the node is "running".
virtual void cleanup ()
 Stops all running actions and schedulers.
virtual Scene * getScene () const
 Returns the Scene that contains the Node.
virtual Rect getWorldBoundingBox () const
 Returns an AABB (axis-aligned bounding-box) in its world's coordinate system.
virtual void setEventDispatcher (EventDispatcher *dispatcher)
 Set event dispatcher for scene.
virtual EventDispatcher * getEventDispatcher () const
 Get the event dispatcher of scene.
virtual uint8_t getOpacity () const
 Return the node's opacity.
virtual uint8_t getDisplayedOpacity () const
 Return the node's display opacity.
virtual void setOpacity (uint8_t opacity)
 Change node opacity.
bool isCascadeOpacityEnabled () const
 Whether cascadeOpacity is enabled or not.
virtual void setCascadeOpacityEnabled (bool cascadeOpacityEnabled)
 Change node's cascadeOpacity property.
virtual const Color32 & getColor () const
 Query node's color value.
virtual const Color32 & getDisplayedColor () const
 Query node's displayed color.
virtual void setColor (const Color32 &color)
 Change the color of node.
bool isCascadeColorEnabled () const
 Query whether cascadeColor is enabled or not.
virtual void setCascadeColorEnabled (bool cascadeColorEnabled)
 Sets whether to enable color cascade.
void setOnEnterCallback (const std::function< void()> &callback)
 Set the callback of event onEnter.
const std::function< void()> & getOnEnterCallback () const
 Get the callback of event onEnter.
void setOnExitCallback (const std::function< void()> &callback)
 Set the callback of event onExit.
const std::function< void()> & getOnExitCallback () const
 Get the callback of event onExit.
void setOnEnterTransitionDidFinishCallback (const std::function< void()> &callback)
 Set the callback of event EnterTransitionDidFinish.
const std::function< void()> & getOnEnterTransitionDidFinishCallback () const
 Get the callback of event EnterTransitionDidFinish.
void setOnExitTransitionDidStartCallback (const std::function< void()> &callback)
 Set the callback of event ExitTransitionDidStart.
const std::function< void()> & getOnExitTransitionDidStartCallback () const
 Get the callback of event ExitTransitionDidStart.
void setOnCleanupCallback (const std::function< void()> &callback)
 Set the callback invoked by cleanup before actions and scheduled callbacks are released.
unsigned short getCameraMask () const
 get & set camera mask, the node is visible by the camera whose camera flag & node's camera mask is true
void applyMaskOnEnter (bool applyChildren)
 Should addChild() make the child follow it's parent's mask?
rhi::ProgramState * setProgramStateByProgramId (uint64_t progId)
 Sets ProgramState by programId.
void resetChild (Node *child, bool cleanup)
 Performs pointer hit testing for this node under the specified camera.
virtual void setLocalZOrder (int localZOrder)
 LocalZOrder is the 'key' used to sort the node relative to its siblings.
void updateOrderOfArrival ()
 !
virtual int getLocalZOrder () const
 Gets the local Z order of this node.
virtual float getGlobalZOrder () const
 Returns the Node's Global Z Order.
virtual void setScaleX (float scaleX)
 Sets the scale (x) of the node.
virtual float getScaleX () const
 Returns the scale factor on X axis of this node.
virtual void setScaleY (float scaleY)
 Sets the scale (y) of the node.
virtual float getScaleY () const
 Returns the scale factor on Y axis of this node.
virtual void setScaleZ (float scaleZ)
 Changes the scale factor on Z axis of this node.
virtual float getScaleZ () const
 Returns the scale factor on Z axis of this node.
virtual void setScale (float scale)
 Sets the scale (x,y,z) of the node.
virtual float getScale () const
 Gets the scale factor of the node, when X and Y have the same scale factor.
virtual void setScale (float scaleX, float scaleY)
 Sets the scale (x,y) of the node.
virtual void setPosition (const Vec2 &position)
 Sets the position (x,y) of the node in its parent's coordinate system.
virtual void setPositionNormalized (const Vec2 &position)
 Sets the position (x,y) using values between 0 and 1.
virtual const Vec2 & getPosition () const
 Gets the position (x,y) of the node in its parent's coordinate system.
virtual const Vec2 & getPositionNormalized () const
 Returns the normalized position.
virtual void setPosition (float x, float y)
 Sets the position (x,y) of the node in its parent's coordinate system.
virtual void getPosition (float *x, float *y) const
 Gets position in a more efficient way, returns two number instead of a Vec2 object.
virtual void setPositionX (float x)
 Gets/Sets x or y coordinate individually for position.
virtual float getPositionX () const
 Gets the x coordinate of the node in its parent's coordinate system.
virtual void setPositionY (float y)
 Sets the y coordinate of the node in its parent's coordinate system.
virtual float getPositionY () const
 Gets the y coordinate of the node in its parent's coordinate system.
virtual void setPosition3D (const Vec3 &position)
 Sets the position (X, Y, and Z) in its parent's coordinate system.
virtual Vec3 getPosition3D () const
 Returns the position (X,Y,Z) in its parent's coordinate system.
virtual void setPositionZ (float positionZ)
 Sets the 'z' coordinate in the position.
virtual float getPositionZ () const
 Gets position Z coordinate of this node.
virtual void setSkewX (float skewX)
 Changes the X skew angle of the node in degrees.
virtual float getSkewX () const
 Returns the X skew angle of the node in degrees.
virtual void setSkewY (float skewY)
 Changes the Y skew angle of the node in degrees.
virtual float getSkewY () const
 Returns the Y skew angle of the node in degrees.
virtual void setAnchorPoint (const Vec2 &anchorPoint)
 Sets the anchor point in percent.
virtual const Vec2 & getAnchorPoint () const
 Returns the anchor point in percent.
virtual const Vec2 & getAnchorPointInPoints () const
 Returns the anchorPoint in absolute pixels.
virtual void setContentSize (const Vec2 &contentSize)
 Sets the untransformed size of the node.
virtual void setVisible (bool visible)
 Sets whether the node is visible.
virtual bool isVisible () const
 Determines if the node is visible.
virtual void setRotation (float rotation)
 Sets the rotation (angle) of the node in degrees.
virtual float getRotation () const
 Returns the rotation of the node in degrees.
virtual void setRotation3D (const Vec3 &rotation)
 Sets the rotation (X,Y,Z) in degrees.
virtual Vec3 getRotation3D () const
 Returns the rotation (X,Y,Z) in degrees.
virtual void setRotationQuat (const Quat &quat)
 Set rotation by quaternion.
virtual Quat getRotationQuat () const
 Return the rotation by quaternion, Note that when _rotationZ_X == _rotationZ_Y, the returned quaternion equals to RotationZ_X * RotationY * RotationX, it equals to RotationY * RotationX otherwise.
virtual void setRotationSkewX (float rotationX)
 Sets the X rotation (angle) of the node in degrees which performs a horizontal rotational skew.
virtual float getRotationSkewX () const
 Gets the X rotation (angle) of the node in degrees which performs a horizontal rotation skew.
virtual void setRotationSkewY (float rotationY)
 Sets the Y rotation (angle) of the node in degrees which performs a vertical rotational skew.
virtual float getRotationSkewY () const
 Gets the Y rotation (angle) of the node in degrees which performs a vertical rotational skew.
virtual void setIgnoreAnchorPointForPosition (bool ignore)
 Sets whether the anchor point will be (0,0) when you position this node.
virtual bool isIgnoreAnchorPointForPosition () const
 Gets whether the anchor point will be (0,0) when you position this node.
virtual int getTag () const
 Returns a tag that is used to identify the node easily.
virtual void setTag (int tag)
 Changes the tag that is used to identify the node easily.
virtual std::string_view getName () const
 Returns a string that is used to identify the node.
virtual void setName (std::string_view name)
 Changes the name that is used to identify the node easily.
virtual void * getUserData ()
 Returns a custom user data pointer.
virtual const void * getUserData () const
 @lua NA
virtual void setUserData (void *userData)
 Sets a custom user data pointer.
virtual Object * getUserObject ()
 Returns a user assigned Object.
virtual const Object * getUserObject () const
 @lua NA
virtual void setUserObject (Object *userObject)
 Returns a user assigned Object.
virtual void onEnter ()
 Event callback that is invoked every time when Node enters the 'stage'.
virtual void onEnterTransitionDidFinish ()
 Event callback that is invoked when the Node enters in the 'stage'.
virtual void onExit ()
 Event callback that is invoked every time the Node leaves the 'stage'.
virtual void onExitTransitionDidStart ()
 Event callback that is called every time the Node leaves the 'stage'.
virtual void setActionManager (ActionManager *actionManager)
 Sets the ActionManager object that is used by all actions.
virtual ActionManager * getActionManager ()
 Gets the ActionManager object that is used by all actions.
virtual Action * runAction (Action *action)
 Executes an action, and returns the action that is executed.
void stopAllActions ()
 Stops and removes all actions from the running action list .
void stopAction (Action *action)
 Stops and removes an action from the running action list.
void stopActionByTag (int tag)
 Removes an action from the running action list by its tag.
void stopAllActionsByTag (int tag)
 Removes all actions from the running action list by its tag.
void stopActionsByFlags (unsigned int flags)
 Removes all actions from the running action list by its flags.
Action * getActionByTag (int tag)
 Gets an action from the running action list by its tag.
ssize_t getNumberOfRunningActions () const
 Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays).
ssize_t getNumberOfRunningActionsByTag (int tag) const
 Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays) with a specific tag.
virtual void setScheduler (Scheduler *scheduler)
 Sets a Scheduler object that is used to schedule all "updates" and timers.
virtual Scheduler * getScheduler ()
 Gets a Scheduler object.
bool isScheduled (SEL_SCHEDULE selector) const
 Checks whether a selector is scheduled.
bool isScheduled (std::string_view key) const
 Checks whether a lambda function is scheduled.
void scheduleUpdate ()
 Schedules the "update" method.
void scheduleUpdateWithPriority (int priority)
 Schedules the "update" method with a custom priority.
void schedule (SEL_SCHEDULE selector, float interval, unsigned int repeat, float delay)
 Schedules a custom selector.
void schedule (SEL_SCHEDULE selector, float interval)
 Schedules a custom selector with an interval time in seconds.
void scheduleOnce (SEL_SCHEDULE selector, float delay)
 Schedules a selector that runs only once, with a delay of 0 or larger.
void scheduleOnce (const std::function< void(float)> &callback, float delay, std::string_view key)
 Schedules a lambda function that runs only once, with a delay of 0 or larger.
void schedule (SEL_SCHEDULE selector)
 Schedules a custom selector, the scheduled selector will be ticked every frame.
void schedule (const std::function< void(float)> &callback, std::string_view key)
 Schedules a lambda function.
void schedule (const std::function< void(float)> &callback, float interval, std::string_view key)
 Schedules a lambda function.
void schedule (const std::function< void(float)> &callback, float interval, unsigned int repeat, float delay, std::string_view key)
 Schedules a lambda function.
void unschedule (SEL_SCHEDULE selector)
 Unschedules a custom selector.
void unschedule (std::string_view key)
 Unschedules a lambda function.
void unscheduleAllCallbacks ()
 Unschedule all scheduled selectors and lambda functions: custom selectors, and the 'update' selector and lambda functions.
virtual void resume ()
 Resumes all scheduled selectors, actions and event listeners.
virtual void pause ()
 Pauses all scheduled selectors, actions and event listeners.
virtual void update (float delta)
 Update method will be called automatically every frame if "scheduleUpdate" is called, and the node is "live".
virtual void updateTransform ()
 Calls children's updateTransform() method recursively.
virtual const Mat4 & getNodeToParentTransform () const
 Returns the matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual Mat4 getNodeToParentTransform (Node *ancestor) const
 Returns the matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual AffineTransform getNodeToParentAffineTransform (Node *ancestor) const
 Returns the affine transform matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual void setNodeToParentTransform (const Mat4 &transform)
 Sets the transformation matrix manually.
virtual const Mat4 & getParentToNodeTransform () const
 Returns the matrix that transform parent's space coordinates to the node's (local) space coordinates.
virtual Mat4 getNodeToWorldTransform () const
 Returns the world affine transform matrix.
virtual Mat4 getWorldToNodeTransform () const
 Returns the inverse world affine transform matrix.
Vec2 convertToNodeSpace (const Vec2 &worldPoint) const
 Converts a Vec2 to node (local) space coordinates.
Vec2 convertToWorldSpace (const Vec2 &nodePoint) const
 Converts a Vec2 to world space coordinates.
Vec2 convertToNodeSpaceAR (const Vec2 &worldPoint) const
 Converts a Vec2 to node (local) space coordinates.
Vec2 convertToWorldSpaceAR (const Vec2 &nodePoint) const
 Converts a local Vec2 to world space coordinates.The result is in Points.
Vec2 convertPointerToNodeSpace (PointerEvent *event) const
 convenience methods which take a Touch instead of Vec2.
Vec2 convertPointerToNodeSpaceAR (PointerEvent *event) const
 converts a Touch (world coordinates) into a local coordinate.
Vec2 getWorldPosition () const
 Gets position of node in world space.
void setWorldPosition (const Vec2 &position)
 Sets position of node in world space.
void setAdditionalTransform (const Mat4 *additionalTransform)
 Sets an additional transform matrix to the node.
Component * getComponent (std::string_view name)
 Gets a component by its name.
virtual bool addComponent (Component *component)
 Adds a component.
virtual bool removeComponent (std::string_view name)
 Removes a component by its name.
virtual bool removeComponent (Component *component)
 Removes a component by its pointer.
virtual void removeAllComponents ()
 Removes all components.
virtual void addChild (Node *child)
 Adds a child to the container with z-order as 0.
virtual void addChild (Node *child, int localZOrder)
 Adds a child to the container with a local z-order.
virtual void addChild (Node *child, int localZOrder, int tag)
 Adds a child to the container with z order and tag.
virtual void addChild (Node *child, int localZOrder, std::string_view name)
 Adds a child to the container with z order and tag.
virtual Node * getChildByTag (int tag) const
 Gets a child from the container with its tag.
template<typename T>
T getChildByTag (int tag) const
 Gets a child from the container with its tag that can be cast to Type T.
virtual Node * getChildByName (std::string_view name) const
 Gets a child from the container with its name.
template<typename T>
T getChildByName (std::string_view name) const
 Gets a child from the container with its name that can be cast to Type T.
virtual void enumerateChildren (std::string_view name, std::function< bool(Node *node)> callback) const
 Search the children of the receiving node to perform processing for nodes which share a name.
virtual Vector< Node * > & getChildren ()
 Returns the array of the node's children.
virtual ssize_t getChildrenCount () const
 Returns the amount of children.
virtual void setParent (Node *parent)
 Sets the parent node.
virtual Node * getParent ()
 Returns a pointer to the parent node.
virtual void removeFromParent ()
 Removes this node itself from its parent node with a cleanup.
virtual void removeFromParentAndCleanup (bool cleanup)
 Removes this node itself from its parent node.
virtual void removeChildByTag (int tag, bool cleanup=true)
 Removes a child from the container by tag value.
virtual void removeChildByName (std::string_view name, bool cleanup=true)
 Removes a child from the container by tag value.
virtual void removeAllChildren ()
 Removes all children from the container with a cleanup.
virtual void reorderChild (Node *child, int localZOrder)
 Reorders a child according to a new z value.
virtual void sortAllChildren ()
 Sorts the children array once before drawing, instead of every time when a child is added or reordered.
Public Member Functions inherited from Object
void retain ()
 Retains the ownership.
void release ()
 Releases the ownership immediately.
Object * autorelease ()
 Releases the ownership sometime soon automatically.
unsigned int getReferenceCount () const
 Returns the Object's current reference count.
uint64_t getObjectID () const noexcept
 Returns the process-local diagnostic identifier assigned at construction.
virtual ~Object ()
 Destructor.

Static Public Member Functions

Creators
static Label * create ()
 Allocates and initializes a Label, with default settings.
static Label * create (std::string_view text, std::string_view fontName, float fontSize)
 Create a Label with automatic font type detection.
static Label * createWithSystemFont (std::string_view text, std::string_view font, float fontSize, const Vec2 &dimensions=Vec2::zero, TextHAlignment hAlignment=TextHAlignment::LEFT, TextVAlignment vAlignment=TextVAlignment::TOP)
 Allocates and initializes a Label, base on platform-dependent API.
static Label * createWithTTF (std::string_view text, std::string_view fontFilePath, float fontSize, const Vec2 &dimensions=Vec2::zero, TextHAlignment hAlignment=TextHAlignment::LEFT, TextVAlignment vAlignment=TextVAlignment::TOP)
 Allocates and initializes a Label, base on FreeType2.
static Label * createWithTTF (const TTFConfig &ttfConfig, std::string_view text, TextHAlignment hAlignment=TextHAlignment::LEFT, int maxLineWidth=0)
 Allocates and initializes a Label, base on FreeType2.
static Label * createWithBMFont (std::string_view bmfontPath, std::string_view text, const TextHAlignment &hAlignment=TextHAlignment::LEFT, int maxLineWidth=0)
 Allocates and initializes a Label, with a bitmap font file.
static Label * createWithBMFont (std::string_view bmfontPath, std::string_view text, const TextHAlignment &hAlignment, int maxLineWidth, const Rect &imageRect, bool imageRotated)
 Allocates and initializes a Label, with a bitmap font file.
static Label * createWithBMFont (std::string_view bmfontPath, std::string_view text, const TextHAlignment &hAlignment, int maxLineWidth, std::string_view subTextureKey)
 Allocates and initializes a Label, with a bitmap font file.
static Label * createWithCharMap (std::string_view charMapFile, int itemWidth, int itemHeight, int startCharMap)
 Allocates and initializes a Label, with char map configuration.
static Label * createWithCharMap (Texture2D *texture, int itemWidth, int itemHeight, int startCharMap)
 Allocates and initializes a Label, with char map configuration.
static Label * createWithCharMap (std::string_view plistFile)
 Allocates and initializes a Label, with char map configuration.
static Node * create ()
 Allocates and initializes a node.
static int getAttachedNodeCount ()
 Gets count of nodes those are attached to scene graph.
template<typename _T>
static void sortNodes (ax::Vector< _T * > &nodes)
 Sorts helper function.

Additional Inherited Members

Static Public Attributes inherited from Node
static const int INVALID_TAG = -1
 Default tag used for all the nodes.
Protected Member Functions inherited from Node
void childrenAlloc ()
 lazy allocs
void insertChild (Node *child, int z)
 helper that reorder a child
void detachChild (Node *child, ssize_t index, bool cleanup)
 Removes a child, call child->onExit(), do cleanup, remove it from children array.
Vec2 convertToScreenSpace (const Vec2 &nodePoint) const
 Convert axmol coordinates to UI windows coordinate.
Protected Attributes inherited from Node
float _rotationX
 rotation on the X-axis
float _rotationY
 rotation on the Y-axis
float _rotationZ_X
 rotation angle on Z-axis, component X
float _rotationZ_Y
 rotation angle on Z-axis, component Y
rhi::VertexLayout * _vertexLayout = nullptr
 rotation using quaternion, if _rotationZ_X == _rotationZ_Y, _rotationQuat = RotationZ_X * RotationY * RotationX, else _rotationQuat = RotationY * RotationX
float _scaleX
 scaling factor on x-axis
float _scaleY
 scaling factor on y-axis
float _scaleZ
 scaling factor on z-axis
Vec2 _position
 position of the node
float _positionZ
 OpenGL real Z position.
float _skewX
 skew angle on x-axis
float _skewY
 skew angle on y-axis
Vec2 _anchorPointInPoints
 anchor point in points
Vec2 _anchorPoint
 anchor point normalized (NOT in points)
Vec2 _contentSize
 untransformed size of the node
Mat4 _modelViewTransform
 ModelView transform of the Node.
Mat4 _transform
 transform
Mat4 _inverse
 inverse transform
Mat4 * _additionalTransform
 two transforms needed by additional transforms
float _globalZOrder
 Global order used to sort the node.
Vector< Node * > _children
 array of children nodes
NodeIndexerMap_t * _childrenIndexer
 The children indexer for fast find child.
Node * _parent
 weak reference to parent node
int _tag
 a tag. Can be any number you assigned just to identify this node
std::string _name
 a string label, an user defined string to identify this node
uint64_t _hashOfName
 hash value of _name, used for speed in getChildByName
void * _userData
 A user assigned void pointer, Can be point to any cpp object.
Object * _userObject
 A user assigned Object.
Scheduler * _scheduler
 scheduler used to schedule timers and updates
ActionManager * _actionManager
 a pointer to ActionManager singleton, which is used to handle all the actions
EventDispatcher * _eventDispatcher
 event dispatcher used to dispatch all kinds of events
bool _reorderChildDirty
 children order dirty flag
bool _running
 is running
bool _visible
 is this node visible
bool _ignoreAnchorPointForPosition
 true if the Anchor Vec2 will be (0,0) when you position the Node, false otherwise. Used by Layer and Scene.
bool _isTransitionFinished
 flag to indicate whether the transition was finished
bool _contentSizeDirty
 whether or not the contentSize is dirty
bool _transformDirty
 transform dirty flag
bool _inverseDirty
 inverse transform dirty flag
bool _additionalTransformDirty
 transform dirty ?
bool _transformUpdated
 Whether or not the Transform object was updated since the last frame.
ComponentContainer * _componentContainer
 Dictionary of components.

Detailed Description

Label is a subclass of Node that knows how to render text labels.

Label can be created with:

  • A true type font file.
  • A bitmap font file.
  • A char map file.
  • The built in system font.

Bitmap Font supported editors:

Member Enumeration Documentation

◆ Overflow

enum class Overflow
strong
Enumerator
CLAMP 

In CLAMP mode, when label content goes out of the bounding box, it will be clipped.

SHRINK 

In SHRINK mode, the font size will change dynamically to adapt the content size.

RESIZE_HEIGHT 

In RESIZE_HEIGHT mode, you can only change the width of label and the height is changed automatically.

Constructor & Destructor Documentation

◆ ~Label()

virtual ~Label ( )
virtual

Destructor of Label.

@lua NA

Member Function Documentation

◆ create() [1/2]

Label * create ( )
static

Allocates and initializes a Label, with default settings.

Returns
An automatically released Label object.

◆ create() [2/2]

Label * create ( std::string_view text,
std::string_view fontName,
float fontSize )
static

Create a Label with automatic font type detection.

This unified factory method creates a Label using the given text and font name. The fontName parameter can be:

  • A TTF font file path (e.g. "fonts/arial.ttf")
  • A system font name (e.g. "Arial", "Helvetica")
  • A BMFont file path (e.g. "fonts/myfont.fnt")

Internally, the method will:

Parameters
textThe text string to render.
fontNameThe font resource identifier (TTF path, system font name, or BMFont path).
fontSizeThe font size in points.
Returns
A new Label instance, or nullptr if creation fails.
Note
This method simplifies font handling by providing a single entry point. Specific createWithTTF(), createWithSystemFont(), and createWithBMFont() methods remain available for explicit control.

◆ createWithSystemFont()

Label * createWithSystemFont ( std::string_view text,
std::string_view font,
float fontSize,
const Vec2 & dimensions = Vec2::zero,
TextHAlignment hAlignment = TextHAlignment::LEFT,
TextVAlignment vAlignment = TextVAlignment::TOP )
static

Allocates and initializes a Label, base on platform-dependent API.

Parameters
textThe initial text.
fontA font family name.
fontSizeThe font size. This value must be > 0.
dimensions
hAlignmentThe text horizontal alignment.
vAlignmentThe text vertical alignment.
Warning
It will generate texture by the platform-dependent code.
Returns
An automatically released Label object.

◆ createWithTTF() [1/2]

Label * createWithTTF ( std::string_view text,
std::string_view fontFilePath,
float fontSize,
const Vec2 & dimensions = Vec2::zero,
TextHAlignment hAlignment = TextHAlignment::LEFT,
TextVAlignment vAlignment = TextVAlignment::TOP )
static

Allocates and initializes a Label, base on FreeType2.

Parameters
textThe initial text.
fontFilePathA font file.
fontSizeThe font size. This value must be > 0.
dimensions
hAlignmentThe text horizontal alignment.
vAlignmentThe text vertical alignment.
Returns
An automatically released Label object.

◆ createWithTTF() [2/2]

Label * createWithTTF ( const TTFConfig & ttfConfig,
std::string_view text,
TextHAlignment hAlignment = TextHAlignment::LEFT,
int maxLineWidth = 0 )
static

Allocates and initializes a Label, base on FreeType2.

Parameters
ttfConfigA pointer to a TTFConfig object.
textThe initial text.
hAlignmentThe text horizontal alignment.
maxLineWidthThe max line width.
Returns
An automatically released Label object.
See also
TTFConfig setTTFConfig setMaxLineWidth

◆ createWithBMFont() [1/3]

Label * createWithBMFont ( std::string_view bmfontPath,
std::string_view text,
const TextHAlignment & hAlignment = TextHAlignment::LEFT,
int maxLineWidth = 0 )
static

Allocates and initializes a Label, with a bitmap font file.

Parameters
bmfontPathA bitmap font file, it's a FNT format.
textThe initial text.
hAlignmentText horizontal alignment.
maxLineWidthThe max line width.
Returns
An automatically released Label object.
See also
setBMFontFilePath setMaxLineWidth

◆ createWithBMFont() [2/3]

Label * createWithBMFont ( std::string_view bmfontPath,
std::string_view text,
const TextHAlignment & hAlignment,
int maxLineWidth,
const Rect & imageRect,
bool imageRotated )
static

Allocates and initializes a Label, with a bitmap font file.

Parameters
bmfontPathA bitmap font file, it's a FNT format.
textThe initial text.
hAlignmentText horizontal alignment.
maxLineWidthThe max line width.
imageRect
imageRotated
Returns
An automatically released Label object.
See also
setBMFontFilePath setMaxLineWidth

◆ createWithBMFont() [3/3]

Label * createWithBMFont ( std::string_view bmfontPath,
std::string_view text,
const TextHAlignment & hAlignment,
int maxLineWidth,
std::string_view subTextureKey )
static

Allocates and initializes a Label, with a bitmap font file.

Parameters
bmfontPathA bitmap font file, it's a FNT format.
textThe initial text.
hAlignmentText horizontal alignment.
maxLineWidthThe max line width.
subTextureKeyName of entry in PLIST texture atlas/sprite sheet
Returns
An automatically released Label object.
See also
setBMFontFilePath setMaxLineWidth

◆ createWithCharMap() [1/3]

Label * createWithCharMap ( std::string_view charMapFile,
int itemWidth,
int itemHeight,
int startCharMap )
static

Allocates and initializes a Label, with char map configuration.

Parameters
charMapFileA char map file, it's a PNG format.
itemWidthThe width in points of each element.
itemHeightThe height in points of each element.
startCharMapThe starting char of the char map.
Returns
An automatically released Label object.

◆ createWithCharMap() [2/3]

Label * createWithCharMap ( Texture2D * texture,
int itemWidth,
int itemHeight,
int startCharMap )
static

Allocates and initializes a Label, with char map configuration.

Parameters
textureA pointer to an existing Texture2D object.
itemWidthThe width in points of each element.
itemHeightThe height in points of each element.
startCharMapThe starting char of the char map.
Returns
An automatically released Label object.

◆ createWithCharMap() [3/3]

Label * createWithCharMap ( std::string_view plistFile)
static

Allocates and initializes a Label, with char map configuration.

Parameters
plistFileA configuration file of char map.
Returns
An automatically released Label object.

◆ setFontInfo()

void setFontInfo ( std::string_view fontName,
float fontSize )

Set font information for the Label.

This method updates the Label's font using the given fontName and fontSize. The fontName parameter can be:

  • A TTF font file path (e.g. "fonts/arial.ttf")
  • A system font name (e.g. "Arial", "Helvetica")
  • A BMFont file path (e.g. "fonts/myfont.fnt")

Internally, the method will:

  • Use BMFont if fontName ends with ".fnt"
  • Use TTF if fontName exists as a TTF file
  • Otherwise, fall back to system font
Parameters
fontNameThe font resource identifier (TTF path, system font name, or BMFont path).
fontSizeThe font size in points.

◆ setTTFConfig()

virtual bool setTTFConfig ( const TTFConfig & ttfConfig)
virtual

Sets a new TTF configuration to Label.

See also
TTFConfig

◆ getTTFConfig()

virtual const TTFConfig & getTTFConfig ( ) const
inlinevirtual

Returns the TTF configuration object used by the Label.

See also
TTFConfig

◆ setCharMap() [1/3]

virtual bool setCharMap ( std::string_view charMapFile,
int itemWidth,
int itemHeight,
int startCharMap )
virtual

Sets a new char map configuration to Label.

See also
createWithCharMap(std::string_view,int,int,int)

◆ setCharMap() [2/3]

virtual bool setCharMap ( Texture2D * texture,
int itemWidth,
int itemHeight,
int startCharMap )
virtual

Sets a new char map configuration to Label.

See also
createWithCharMap(Texture2D*,int,int,int)

◆ setCharMap() [3/3]

virtual bool setCharMap ( std::string_view plistFile)
virtual

Sets a new char map configuration to Label.

See also
createWithCharMap(std::string_view)

◆ setSystemFontName()

virtual void setSystemFontName ( std::string_view font)
virtual

Sets a new system font to Label.

Parameters
fontA font family name.
Warning

◆ requestSystemFontRefresh()

virtual void requestSystemFontRefresh ( )
inlinevirtual
Warning
This method is not recommended for game developers.

◆ getCharCount()

int getCharCount ( ) const

Returns the number of UTF-32 characters.

Returns
int UTF-32 character count

◆ setTextColor()

virtual void setTextColor ( const Color32 & color)
virtual

Sets the text color of Label.

The text color is different from the color of Node.

Warning
Limiting use to only when the Label created with true type font or system font.

◆ enableShadow()

virtual void enableShadow ( const Color32 & shadowColor = Color32::black,
const Vec2 & offset = Vec2(2, -2),
int blurRadius = 0 )
virtual

Enable shadow effect to Label.

◆ enableOutline()

virtual void enableOutline ( const Color32 & outlineColor,
float outlineSize = -1 )
virtual

Enable outline effect to Label.

Warning
Limiting use to only when the Label created with true type font or system font.

◆ enableGlow()

virtual void enableGlow ( const Color32 & glowColor,
float glowRadius = -1 )
virtual

Enable glow effect to Label.

Warning
Limiting use to only when the Label created with true type font.

◆ enableStrikethrough()

void enableStrikethrough ( )

Enables strikethrough.

Underline and Strikethrough cannot be enabled at the same time. Strikethrough is like an underline but at the middle of the glyph

◆ disableEffect() [1/2]

virtual void disableEffect ( )
virtual

Disable all effect applied to Label.

Warning
Please use disableEffect(LabelEffect::ALL) instead of this API.

◆ disableEffect() [2/2]

virtual void disableEffect ( LabelEffect effect)
virtual

Disable effect to Label.

See also
LabelEffect

◆ setLineBreakWithoutSpace()

void setLineBreakWithoutSpace ( bool breakWithoutSpace)

Specify what happens when a line is too long for Label.

Parameters
breakWithoutSpaceLines are automatically broken between words if this value is false.

◆ setMaxLineWidth()

void setMaxLineWidth ( float maxLineWidth)

Makes the Label at most this line untransformed width.

The Label's max line width be used for force line breaks if the value not equal zero.

◆ setBMFontSize()

void setBMFontSize ( float fontSize)

Change font size of label type BMFONT Note: This function only scale the BMFONT letter to mimic the font size change effect.

Parameters
fontSizeThe desired font size in float.

◆ getBMFontSize()

float getBMFontSize ( ) const

Return the user define BMFont size.

Returns
The BMFont size in float value.

◆ enableWrap()

void enableWrap ( bool enable)

Toggle wrap option of the label.

Note: System font doesn't support manually toggle wrap.

Parameters
enableSet true to enable wrap and false to disable wrap.

◆ isWrapEnabled()

bool isWrapEnabled ( ) const

Query the wrap is enabled or not.

Note: System font will always return true.

◆ setOverflow()

void setOverflow ( Overflow overflow)

Change the label's Overflow type, currently only TTF and BMFont support all the valid Overflow type.

Char Map font supports all the Overflow type except for SHRINK, because we can't measure it's font size. System font only support Overflow::Normal and Overflow::RESIZE_HEIGHT.

Parameters
overflowsee Overflow

◆ getOverflow()

Overflow getOverflow ( ) const

Query the label's Overflow type.

Returns
see Overflow

◆ setWidth()

void setWidth ( float width)
inline

Makes the Label exactly this untransformed width.

The Label's width be used for text align if the value not equal zero.

◆ setHeight()

void setHeight ( float height)
inline

Makes the Label exactly this untransformed height.

The Label's height be used for text align if the value not equal zero. The text will display incomplete if the size of Label is not large enough to display all text.

◆ getLetter()

virtual Sprite * getLetter ( int lettetIndex)
virtual

Provides a way to treat each character like a Sprite.

Warning
No support system font.

◆ setLineHeight()

void setLineHeight ( float height)

Sets the line height of the Label.

Warning
Not support system font.
Since
v3.2.0

◆ getLineHeight()

float getLineHeight ( ) const

Returns the line height of this Label.

Warning
Not support system font.
Since
v3.2.0

◆ getLabelType()

LabelType getLabelType ( ) const
inline

Returns type of label.

Warning
Not support system font.
Returns
the type of label
Since
v3.18.0

◆ setAdditionalKerning()

void setAdditionalKerning ( float space)

Sets the additional kerning of the Label.

Warning
Not support system font.
Since
v3.2.0

◆ getAdditionalKerning()

float getAdditionalKerning ( ) const

Returns the additional kerning of the Label.

Warning
Not support system font.
Since
v3.2.0

◆ setProgramState()

bool setProgramState ( rhi::ProgramState * programState,
bool ownPS = false )
overridevirtual

Sets ProgramState with retain.

Parameters
programState

Reimplemented from Node.

◆ isOpacityModifyRGB()

bool isOpacityModifyRGB ( ) const
inlineoverridevirtual

If node opacity will modify the RGB color value, then you should override this method and return true.

Returns
A boolean value, true indicates that opacity will modify color; false otherwise.

Reimplemented from Node.

◆ setOpacityModifyRGB()

void setOpacityModifyRGB ( bool value)
overridevirtual

If you want the opacity affect the color property, then set to true.

Parameters
valueA boolean value.

Reimplemented from Node.

◆ updateDisplayedColor()

void updateDisplayedColor ( const Color32 & parentColor)
overridevirtual

Update node's displayed color with its parent color.

Parameters
parentColorA Color32 color value.

Reimplemented from Node.

◆ updateDisplayedOpacity()

void updateDisplayedOpacity ( uint8_t parentOpacity)
overridevirtual

Update the displayed opacity of node with it's parent opacity;.

Parameters
parentOpacityThe opacity of parent node.

Reimplemented from Node.

◆ getDescription()

std::string getDescription ( ) const
overridevirtual

Gets the description string.

It makes debugging easier.

Returns
A string @lua NA

Reimplemented from Node.

◆ getContentSize()

const Vec2 & getContentSize ( ) const
overridevirtual

Returns the untransformed size of the node.

See also
setContentSize(const Vec2&)
Returns
The untransformed size of the node.

Reimplemented from Node.

◆ getBoundingBox()

Rect getBoundingBox ( ) const
overridevirtual

Returns an AABB (axis-aligned bounding-box) in its parent's coordinate system.

Returns
An AABB (axis-aligned bounding-box) in its parent's coordinate system

Reimplemented from Node.

◆ visit()

void visit ( const SceneRenderState & state,
const Mat4 & parentTransform,
uint32_t parentFlags )
overridevirtual

Visits this node's children and draw them recursively.

Parameters
stateA scene render traversal state.
parentTransformA transform matrix.
parentFlagsRenderer flag.

Reimplemented from Node.

◆ draw()

void draw ( const SceneRenderState & state,
const Mat4 & transform,
uint32_t flags )
overridevirtual

Override this method to draw your own node.

The following GL states will be enabled by default:

  • glEnableClientState(GL_VERTEX_ARRAY);
  • glEnableClientState(GL_COLOR_ARRAY);
  • glEnableClientState(GL_TEXTURE_COORD_ARRAY);
  • glEnable(GL_TEXTURE_2D); AND YOU SHOULD NOT DISABLE THEM AFTER DRAWING YOUR NODE But if you enable any other GL state, you should disable it after drawing your node.
Parameters
stateA scene render traversal state.
transformA transform matrix.
flagsRenderer flag.

Reimplemented from Node.

◆ setCameraMask()

void setCameraMask ( unsigned short mask,
bool applyChildren = true )
overridevirtual

Modify the camera mask for current node.

If applyChildren is true, then it will modify the camera mask of its children recursively.

Parameters
maskA unsigned short bit for mask.
applyChildrenA boolean value to determine whether the mask bit should apply to its children or not.

Reimplemented from Node.

◆ removeAllChildrenWithCleanup()

void removeAllChildrenWithCleanup ( bool cleanup)
overridevirtual

Removes all children from the container, and do a cleanup to all running actions depending on the cleanup parameter.

Parameters
cleanupTrue if all running actions on all children nodes should be cleanup, false otherwise. @lua removeAllChildren

Reimplemented from Node.

◆ removeChild()

void removeChild ( Node * child,
bool cleanup = true )
overridevirtual

Removes a child from the container.

It will also cleanup all running actions depending on the cleanup parameter.

Parameters
childThe child node which will be removed.
cleanupTrue if all running actions and callbacks on the child node will be cleanup, false otherwise.

Reimplemented from Node.

◆ setGlobalZOrder()

void setGlobalZOrder ( float globalZOrder)
overridevirtual

Defines the order in which the nodes are renderer.

Nodes that have a Global Z Order lower, are renderer first.

In case two or more nodes have the same Global Z Order, the order is not guaranteed. The only exception if the Nodes have a Global Z Order == 0. In that case, the Scene Graph order is used.

By default, all nodes have a Global Z Order = 0. That means that by default, the Scene Graph order is used to render the nodes.

Global Z Order is useful when you need to render nodes in an order different than the Scene Graph order.

Limitations: Global Z Order can't be used by Nodes that have SpriteBatchNode as one of their ancestors. And if ClippingNode is one of the ancestors, then "global Z order" will be relative to the ClippingNode.

See also
setLocalZOrder()
setVertexZ()
Since
v3.0
Parameters
globalZOrderThe global Z order value.

Reimplemented from Node.


The documentation for this class was generated from the following file:
  • Label.h