cocos代码研究（2）Label学习笔记

理论部分

Label类继承自Node类，中文翻译文字与字体，通常在应用开发中为模块作为提示和描述的作用，主要有3中不同的创建方式。

1.通过ttf字体包创建，通过指定本地已有的ttf格式的字体文件，创建Label。

• 优点：这种字体格式一般就是网上字体库下载下来的格式，往往对一种语言的文字支持比较全面，可以随意设置字体的大小。
• 缺点：一个字体ttf支持的文字较多，导致了体积庞大，字体描绘的效率低，不适合更新频繁的Label使用。

2.通过fnt格式文件创建，通过指定本地已有的fnt格式的文件，创建Label，fnt的文件可以由ttf字体库文件通过BMFont工具转换过来，原理就是我们根据实际需要的文字信息从ttf字体库中选取这部分文字字形出来，给他们创建一个纹理图集，通过创建的纹理图集和创建我们需要的文字Label。（注 .fnt文件格式都会有一个同名的纹理图集.png）

• 优点：效率高，自由度高。
• 缺点：字形支持不多，不可以设置字体大小。

3.通过设定字形图集来创建文字Label，图集要求每一个字形占据的空间都是等宽等高，并记录下这些宽高的具体数据，这种创建一般都是字形很少的情况下，如0...9, a...z, A...Z。

代码部分

静态创建API

基于平台相关的API创建和初始化一个文本。

static Label* createWithSystemFont(const std::string & text,　　//最始文本内容。
　　　　　　　　　　　　　　　　　　 const std::string & font,　　//一个字体文件或字体名称。
　　　　　　　　　　　　　　　　　　 float fontSize,　　//字体大小。这个值必须大于0。
　　　　　　　　　　　　　　　　　　 const Size & dimensions = Size::ZERO,　　//文本的内容大小。
　　　　　　　　　　　　　　　　　　 TextHAlignment hAlignment = TextHAlignment::LEFT,　　//水平对齐方式。
　　　　　　　　　　　　　　　　　　 TextVAlignment vAlignment = TextVAlignment::TOP)　　//垂直对齐方式。

实例：

auto label = Label::createWithSystemFont("Cocos2d-x Label Test", "arial", 24); //arial=字体名称
auto labelA = Label::createWithSystemFont("create label with system font", "fonts/arial.ttf", 24); //fonts/arial.ttf=字体文件
auto label = Label::createWithSystemFont("Hello World!", "fonts/arial.ttf", 24, Size(30,100));  //Size(30,100)=文本大小

使用FreeType2库创建和初始化一个文本。

static Label* createWithTTF(const std::string & text,　　//最初文本内容。
　　　　　　　　　　　　　　 const std::string & fontFilePath,　　//一个TTF字体文件。
　　　　　　　　　　　　　　 float fontSize,　　//字体大小。这个值必须大于0。
　　　　　　　　　　　　　　 const Size & dimensions = Size::ZERO,　　//文本的内容大小
　　　　　　　　　　　　　　 TextHAlignment hAlignment = TextHAlignment::LEFT,　　//水平对齐方式。
　　　　　　　　　　　　　　 TextVAlignment vAlignment = TextVAlignment::TOP)　　//垂直对齐方式

实例：

auto label = Label::createWithTTF("create label with TTF", "fonts/arial.ttf", 24);

使用FreeType2库创建和初始化一个文本

static Label* createWithTTF(const TTFConfig & ttfConfig,　　//一个TTFConfig对象实例。
　　　　　　　　　　　　　　 const std::string & text,　　//最初文本内容。
　　　　　　　　　　　　　　 TextHAlignment hAlignment = TextHAlignment::LEFT,　　//水平对齐方式
　　　　　　　　　　　　　　 int maxLineWidth = 0)　　//最大线宽

实例：

TTFConfig ttfConfig("fonts/arial.ttf", 18);
auto label = Label::createWithTTF(ttfConfig,"label text", TextHAlignment::CENTER);

使用位图字体文件创建和初始化一个文本。

static Label* createWithBMFont(const std::string & bmfontPath,　　//一个位图字体文件,它是FNT格式。
　　　　　　　　　　　　　　　　 const std::string & text,　　//初始文本内容。
　　　　　　　　　　　　　　　　 const TextHAlignment & hAlignment = TextHAlignment::LEFT,　　//水平对齐方式。
　　　　　　　　　　　　　　　　 int maxLineWidth = 0,　　//最大线宽
　　　　　　　　　　　　　　　　 const Vec2 & imageOffset = Vec2::ZERO)　　//第一个字符的在位图文件中的偏移。

实例：

auto label = Label::createWithBMFont("fonts/bitmapFontTest2.fnt", "Test");

使用字符映射文件来创建和初始化一个文本。

static Label* createWithCharMap    (const std::string & plistFile)    　　//一个字符映射的配置文件

实例：

auto label = Label::createWithCharMap("fonts/tuffy_bold_italic-charmap.plist");

Public API

virtual void removeAllChildrenWithCleanup(bool cleanup) override
从容器中删除所有的子节点, 取决于cleanup参数，同时可能会清除所有的活动的动作。

virtual void removeChild(Node *child, bool cleanup=true) override
从容器中删除一个节点，取决于cleanup参数，同时可能会清除所有的活动的动作。

virtual const Size & getContentSize() const override
返回节点未变形状态下的大小。

virtual void setString(const std::string &text) override
设置文本显示的字符串。

virtual const std::string & getString() const override
返回文本显示的字符串。

int getStringLength()
获取字符串的长度

virtual void setTextColor(const Color4B &color)
设置文本的字符串的颜色。

const Color4B & getTextColor() const
返回文本的字符串的颜色。

void setAlignment(TextHAlignment hAlignment)
设置文本的水平对齐。

TextHAlignment getTextAlignment() const
获取文本的对齐方式。

void setVerticalAlignment(TextVAlignment vAlignment)
设置文本垂直对齐。

TextVAlignment getVerticalAlignment() const
返回文本垂直对齐。

void setAlignment(TextHAlignment hAlignment, TextVAlignment vAlignment)
设置文本的水平和垂直对齐方式。

void setLineBreakWithoutSpace(bool breakWithoutSpace)
指定当文本太长时，是否需要换行。

void setMaxLineWidth(float maxLineWidth)
设置文本的最大行宽。 如果文本的行宽不等于零的话，那么它可以用来强制换行。

float getMaxLineWidth()
获取文本的最大行宽

void setWidth(float width)
设置文本的行宽

float getWidth() const
返回文本的行宽

void setHeight(float height)
设置文本的行高

float getHeight() const
返回文本的行高

int getStringNumLines()
获取文本显示的行数。

virtual void enableShadow(const Color4B &shadowColor=Color4B::BLACK, const Size &offset=Size(2,-2), int blurRadius=0)
激活文本的阴影效果

virtual void enableOutline(const Color4B &outlineColor, int outlineSize=-1)
激活文本的描边效果。

virtual void enableGlow(const Color4B &glowColor)
激活文本的发光效果

virtual void disableEffect()
禁用所有文本特效。

virtual void disableEffect(LabelEffect effect)
禁用文本特效。

void setHorizontalAlignment(TextHAlignment hAlignment)
设置文本的水平对齐。

TextHAlignment getHorizontalAlignment() const
返回文本的水平对齐。

void setLineHeight(float height)
设置文本的行高。

float getLineHeight() const
返回这个文本的行高。

void setAdditionalKerning(float space)
设置文本的字符间距。

float getAdditionalKerning() const
返回文本的字符间距

void setDimensions(float width, float height)
更高效地设置文本大小的方法。这个大小是未进行坐标变换的大小。

const Size & getDimensions() const
获取文本的大小

virtual void updateContent()
立即更新文本内容。

virtual Sprite * getLetter(int lettetIndex)
提供了一种方法,可以把每个字符当作精灵来看待。

void setClipMarginEnabled(bool clipEnabled)
设置是否裁剪文本上下边距，主要用来减少文本的调试。

bool isClipMarginEnabled() const
判断文本是否裁剪上下边距

FontAtlas * getFontAtlas()
返回一个FontAtlas对象指针

virtual std::string getDescription() const override
得到描述性的字符串。这将会使得调试更加简单。

virtual Rect getBoundingBox() const override
返回父坐标系中的一个AABB(轴向包围外框)。

virtual void visit(Renderer *renderer, const Mat4 &parentTransform, uint32_t parentFlags) override
遍历所有子节点，并且循环递归得发送它们的渲染指令。

virtual void draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) override
重写这个方法来绘制你自己的节点。 以下的GL状态是默认开启的：

virtual void setGlobalZOrder(float globalZOrder) override
定义渲染节点的顺序 拥有全局Z顺序越小的节点，最先渲染