‎Cocos2d-x 学习笔记(18) Label

1. 简介

Label直接继承了Node LabelProtocol BlendProtocol，用于渲染文本，让文本呈现的效果丰富。

Label有4种类型，：

    enum class LabelType {

        TTF,

        BMFONT,

        CHARMAP,

        STRING_TEXTURE

    };

Label文本呈现的效果：

enum class LabelEffect {

    NORMAL,

    OUTLINE,

    SHADOW,

    GLOW,

    ITALICS,

    BOLD,

    UNDERLINE,

    STRIKETHROUGH,

    ALL

};

针对Label大小范围与文本长度冲突时的4种操作，用枚举定义：

    enum class Overflow

    {

        //In NONE mode, the dimensions is (0,0) and the content size will change dynamically to fit the label.

        NONE,

        /**

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

         */

        CLAMP,

        /**

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

         */

        SHRINK,

        /**

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

         */

        RESIZE_HEIGHT

    };

2. 构造函数

从构造函数得知：

锚点(0.5,0.5)

调用reset()方法

LabelType默认STRING_TEXTURE

LabelEffect默认NORMAL

设置了默认字体和大小

label长宽大小默认0

对齐方式默认LEFT TOP

文本颜色默认白色，效果颜色默认黑色

Overflow默认NONE

3. create

create()

创建空的label对象和指针。

createWithSystemFont

Label* createWithSystemFont(const std::string& text, const std::string& font, float fontSize,

        const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT,

        TextVAlignment vAlignment = TextVAlignment::TOP)

共6个参数：

string& text 要显示的字符串
string& font 字体，字体名/字体文件
float fontSize 字体大小，必须大于0
Size& dimensions = Size::ZERO label大小，默认Size(0, 0)
TextHAlignment hAlignment = TextHAlignment::LEFT 水平对齐方式，默认左对齐
TextVAlignment vAlignment = TextVAlignment::TOP 垂直对齐方式，默认顶部对齐

实现：

    auto ret = new (std::nothrow) Label(hAlignment,vAlignment);

    if (ret)

    {

        ret->setSystemFontName(font);

        ret->setSystemFontSize(fontSize);

        ret->setDimensions(dimensions.width, dimensions.height);

        ret->setString(text);

        ret->autorelease();

        return ret;

    }

    return nullptr;

通过set方法用参数进行set。

setSystemFontName
_systemFont设为参数字体
_currentLabelType = LabelType::STRING_TEXTURE
_systemFontDirty = true
setSystemFontSize　
_systemFontSize _originalFontSize 设为参数字体大小
_currentLabelType = LabelType::STRING_TEXTURE;
_systemFontDirty = true　　
setDimensions
如果Overflow为RESIZE_HEIGHT类型，先将参数height设0
_labelWidth = width;
_labelHeight = height;
_labelDimensions.width = width;
_labelDimensions.height = height;
_maxLineWidth = width; //最大文本宽度

_contentDirty = true;

如果Overflow是SHRINK类型，

　　if (_originalFontSize > 0) {
this->restoreFontSize();
}
setString
_utf8Text _utf32Text 都存储了set的字符串

createWithTTF

有2种重载方法：

方法1：参数中用string& fontFilePath指定字符串字体文件.ttf路径

Label * createWithTTF(const std::string& text, const std::string& fontFilePath, float fontSize,

        const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT,

        TextVAlignment vAlignment = TextVAlignment::TOP)

参数中没有ttf，利用参数生成对应的ttf，之后调用了setTTFConfig(ttfConfig)
还调用了setDimensions(dimensions.width, dimensions.height); setString(text);

方法2：参数中用TTFConfig设置字体，maxLineWidth值为最大文本行宽（默认为0，表示不设置）

Label* createWithTTF(const TTFConfig& ttfConfig, const std::string& text,

        TextHAlignment hAlignment = TextHAlignment::LEFT, int maxLineWidth = )

　　对参数ttfConfig调用了setTTFConfig(ttfConfig)，之后执行setMaxLineWidth(maxLineWidth); setString(text);

字体配置TTFConfig是一个结构体：

typedef struct _ttfConfig

{

    std::string fontFilePath; //字体文件路径，默认空

    float fontSize; //字体大小，默认12

    GlyphCollection glyphs; //字符集，默认DYNAMIC

    const char *customGlyphs; //自定义字符集, 默认无

    bool distanceFieldEnabled; //是否字体紧凑，默认false

    int outlineSize; //字体轮廓大小，默认0

    bool italics; //是否斜体，默认false

    bool bold; //是否粗体，默认false

    bool underline; //是否有下划线，默认false

    bool strikethrough; //是否有删除线，默认false

    _ttfConfig(..........)

        : fontFilePath(filePath)

        , fontSize(size)

        , glyphs(glyphCollection)

        , customGlyphs(customGlyphCollection)

        , distanceFieldEnabled(useDistanceField)

        , outlineSize(outline)

        , italics(useItalics)

        , bold(useBold)

        , underline(useUnderline)

        , strikethrough(useStrikethrough)

    {

        if(outline > )

        {

            distanceFieldEnabled = false;

        }

    }

} TTFConfig;

setTTFConfig(ttfConfig)

先执行_originalFontSize = ttfConfig.fontSize

再调用setTTFConfigInternal(ttfConfig)

_currentLabelType = LabelType::TTF

createWithBMFont

参数中包括BMFont软件生成的.fnt文件路径和显示的文本。字符串必须和.fnt文件定义的文本一致，否则多余的不显示。

Label* createWithBMFont(const std::string& bmfontPath, const std::string& text,

        const TextHAlignment& hAlignment = TextHAlignment::LEFT, int maxLineWidth = ,

        const Vec2& imageOffset = Vec2::ZERO)

调用了setBMFontFilePath(bmfontFilePath,imageOffset)，_currentLabelType = LabelType::BMFONT

调用了setMaxLineWidth(maxLineWidth) setString(text);

我们使用BMFont能生成自定义字体，软件导出.fnt字体信息文件和.png字体图片文件，两文件放在同一目录被Cocos2dx使用。

createWithCharMap

有三种重载方法：

Label * createWithCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap)

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

Label * createWithCharMap(const std::string& plistFile)

创建方式分为三种：

通过.png图片文件
通过Texture2D纹理
通过.plist文件

前两种方式要在参数中设置表示字符的每个小图的长宽、起始的下标值startCharMap（ASCII，用'0'代替48）。.plist则已经包含了这些参数。

每种重载都调用了对应的setCharMap，其中调用了对应的FontAtlasCache::getFontAtlasCharMap生成newAtlas，再执行

　　_currentLabelType = LabelType::CHARMAP
　　setFontAtlas(newAtlas)

- TTF BMFont CharMap

TTF统一配置字体属性，对label中所有文本都有效。

BMFont需要.fnt .png文件，使用时仅需要.fnt路径，.fnt类似于.plist，通过文本内容选择大图.png中对应的字符。

CharMap可以看作BMFont的简化版，通过ASCII读取大图里不同的字符。

4. 渲染特效

Label提供了三种字体特效：

Shadow 阴影
Outline 描边
Glow 发光

三种特效设置方式：

enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(,-), int blurRadius = )

enableOutline(const Color4B& outlineColor,int outlineSize = -)

enableGlow(const Color4B& glowColor)

描边Outline和发光Glow只支持createWithTTF创建的label。且两者同时使用时，仅后设置的显示。

阴影Shadow的Size是以label的左上角为基准点设置阴影的位置的。

5. 对齐方式

Label默认的对齐方式是LEFT+TOP。

分为水平方向和竖直方向，对应Label两个成员：

    TextHAlignment _hAlignment; //水平

    TextVAlignment _vAlignment; //竖直

定义两个枚举：

enum class CC_DLL TextVAlignment

{

    TOP,

    CENTER,

    BOTTOM

};

enum class CC_DLL TextHAlignment

{

    LEFT,

    CENTER,

    RIGHT

};

6. 范围大小

label所处的文本框大小，涉及变量：

    Size _labelDimensions;

    float _labelWidth;

    float _labelHeight;

7. 文本字体大小颜色

    virtual void setSystemFontName(const std::string& font);

    virtual const std::string& getSystemFontName() const { return _systemFont;}

    virtual void setSystemFontSize(float fontSize);

    virtual float getSystemFontSize() const { return _systemFontSize;}

    virtual void setString(const std::string& text) override;

    virtual const std::string& getString() const override {  return _utf8Text; 　}
　
   //仅ttf systemfont
　　virtual void setTextColor(const Color4B &color);
　　const Color4B& getTextColor() const { return _textColor;}

8. 自动换行行间距

- void setLineBreakWithoutSpace(bool breakWithoutSpace)

是否开启换行功能，设置了属性_lineBreakWithoutSpaces。

- void setMaxLineWidth(float maxLineWidth)

设置最大行宽，需要_labelWidth为0时才能继续设置，否则我们仅通过_labelWidth就能实现自动换行。设置了属性_maxLineWidth。

- label尺寸相关

涉及到_labelDimensions _labelWidth _labelHeight。

    void setWidth(float width) { setDimensions(width,_labelHeight);}

    float getWidth() const { return _labelWidth; }

    void setHeight(float height){ setDimensions(_labelWidth, height); }

    float getHeight() const { return _labelHeight; }

    void setDimensions(float width, float height);

    const Size& getDimensions() const{ return _labelDimensions;}

- void setLineHeight(float height) / float getLineHeight()

直接修改属性_lineHeight。行间距不支持System Font。

- void setAdditionalKerning(float space) / float getAdditionalKerning()

字符间距修改属性_additionalKerning，不支持System Font。