cocos2d-X 节点（CCLabelBMFont.h）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

cocos2d-X 节点（CCLabelBMFont.h）API

温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记

///cocos2d-x-3.0alpha0/cocos2dx/label_nodes

#ifndef __CCBITMAP_FONT_ATLAS_H__
#define __CCBITMAP_FONT_ATLAS_H__

#include "sprite_nodes/CCSpriteBatchNode.h"
#include "support/data_support/uthash.h"
#include <map>
#include <sstream>
#include <iostream>
#include <vector>

NS_CC_BEGIN

/**
 * @addtogroup GUI
 * @{
 * @addtogroup label
 * @{
 */

enum {
    kLabelAutomaticWidth = -1,
};

struct _FontDefHashElement;

/**
@构造 ccBMFontDef
 定义 BMFont
*/
typedef struct _BMFontDef {
    //!字符的识别码
    unsigned int charID;
    //! font 的原始尺寸
    Rect rect;
    //! 绘制图片时 X 轴的偏移量（以像素为单位）
    short xOffset;
    //!  绘制图片时 Y 轴的偏移量（以像素为单位）
    short yOffset;
    //! 绘制当前字符串时移动的位置（以像素为单位）
    short xAdvance;
} ccBMFontDef;

/** @构造 ccBMFontPadding
BMFont 填充
@since v0.8.2
*/
typedef struct _BMFontPadding {
    /// padding left        //填充
    int    left;
    /// padding top        //填充
    int top;
    /// padding right        //填充
    int right;
    /// padding bottom        //填充
    int bottom;
} ccBMFontPadding;

typedef struct _FontDefHashElement
{
	unsigned int	key;		// key. font 的 unicode 编码值
	ccBMFontDef		fontDef;	// 定义 font
	UT_hash_handle	hh;
} tFontDefHashElement;

// targetSet 的 wqual 功能.
typedef struct _KerningHashElement
{
	int				key;		// hash 值. 第一个元素16-bit 第二个元素的 16-bit
	int				amount;
	UT_hash_handle	hh;
} tKerningHashElement;

/** @简要 使用 CCBMFontConfiguration 解析 .fnt 文件的配置
@since v0.8
*/
class CC_DLL CCBMFontConfiguration : public Object
{
    // XXX: 创建一个公共接口 bitmapFontArray[] 是可以使用的
public://@public
    //定义 BMFont 
    tFontDefHashElement *_fontDefDictionary;

    //! FNTConfig: 应该使用共共同的高度(issue（发行编号） #1343)
    int _commonHeight;
    //! 填充
    ccBMFontPadding    _padding;
    //! atlas（大地图） 名字
    std::string _atlasName;
    //! 字体间距
    tKerningHashElement *_kerningDictionary;
    
    // 定义实际存在的字符集字体
    std::set<unsigned int> *_characterSet;
public:
    /**
     * @js ctor
     */
    CCBMFontConfiguration();
    /**
     * @js NA
     * @lua NA
     */
    virtual ~CCBMFontConfiguration();
    /**
     * @js NA
     * @lua NA
     */
    const char * description() const;

    /** 使用 FNT 文件，分配一个 CCBMFontConfiguration*/
    static CCBMFontConfiguration * create(const char *FNTfile);

    /** 使用 FNT 文件，初始化一个 CCBMFontConfiguration*/
    bool initWithFNTfile(const char *FNTfile);
    
    inline const char* getAtlasName(){ return _atlasName.c_str(); }
    inline void setAtlasName(const char* atlasName) { _atlasName = atlasName; }
    
    std::set<unsigned int>* getCharacterSet() const;
private:
    std::set<unsigned int>* parseConfigFile(const char *controlFile);
    void parseCharacterDefinition(std::string line, ccBMFontDef *characterDefinition);
    void parseInfoArguments(std::string line);
    void parseCommonArguments(std::string line);
    void parseImageFileName(std::string line, const char *fntFile);
    void parseKerningEntry(std::string line);
    void purgeKerningDictionary();
    void purgeFontDefDictionary();
};

/** @brief LabelBMFont 是 SpriteBatchNode 的子类.

特点:
- 对待那个字符都想对待 Sprite 一样，这意味着每一个子符都可以：
- rotated（旋转）
- scaled（）（缩放）
- translated（转换）
- tinted（色彩）
-  更改不透明度
- 它可以作为一个菜单项的一部分。
- 可以用来锚点对齐“标签”
- 支持AngelCode文本格式

Limitations:
 - 所有字符的内部都使用锚点（0.5F，0.5F），但是不建议去改变它
 因为它可能会影响渲染

LabelBMFont 实现了 LabelProtocol, 像一个 Label 、 LabelAtlas.
LabelBMFont 是一个灵活的 Label, 他有 LabelAtlas 的速度， Sprite 的所有特性.
如果有疑问，可以使用 LabelBMFont 代替 LabelAtlas / Label.

Supported editors:
http://glyphdesigner.71squared.com/ (Commercial, Mac OS X)
http://www.n4te.com/hiero/hiero.jnlp (Free, Java)
http://slick.cokeandcode.com/demos/hiero.jnlp (Free, Java)
http://www.angelcode.com/products/bmfont/ (Free, Windows only)

@since v0.8
*/

class CC_DLL LabelBMFont : public SpriteBatchNode, public LabelProtocol, public RGBAProtocol
{
public:
    /**
     * @js ctor
     */
    LabelBMFont();
    /**
     * @js NA
     * @lua NA
     */
    virtual ~LabelBMFont();
    /** 清楚缓存数据.
    从缓存中删除配置和 atlas 字典。
    @since v0.99.3
    */
    static void purgeCachedData();

    /** 使用 str 和 FNT 文件创建一个 bitmap（位图） 字体集 */
    static LabelBMFont * create(const char *str, const char *fntFile, float width, TextHAlignment alignment, Point imageOffset);
    
	static LabelBMFont * create(const char *str, const char *fntFile, float width, TextHAlignment alignment);

	static LabelBMFont * create(const char *str, const char *fntFile, float width);

	static LabelBMFont * create(const char *str, const char *fntFile);

    /** 创建一个 label.
     */
    static LabelBMFont * create();

    bool init();
    /** 使用 str 和 FNT 文件初始化一个 bitmap（位图） 字体集 */
    bool initWithString(const char *str, const char *fntFile, float width = kLabelAutomaticWidth, TextHAlignment alignment = TextHAlignment::LEFT, Point imageOffset = Point::ZERO);

    /** 更新要渲染的字符字体*/
    void createFontChars();
    // super method
    virtual void setString(const char *newString);
    virtual void setString(const char *newString, bool needUpdateLabel);

    virtual const char* getString(void) const;
    virtual void setCString(const char *label);
    virtual void setAnchorPoint(const Point& var);
    virtual void updateLabel();
    virtual void setAlignment(TextHAlignment alignment);
    virtual void setWidth(float width);
    virtual void setLineBreakWithoutSpace(bool breakWithoutSpace);
    virtual void setScale(float scale);
    virtual void setScaleX(float scaleX);
    virtual void setScaleY(float scaleY);
    
    // RGBAProtocol 
    virtual bool isOpacityModifyRGB() const;
    virtual void setOpacityModifyRGB(bool isOpacityModifyRGB);
    virtual GLubyte getOpacity() const;
    virtual GLubyte getDisplayedOpacity() const;
    virtual void setOpacity(GLubyte opacity);
    virtual void updateDisplayedOpacity(GLubyte parentOpacity);
    virtual bool isCascadeOpacityEnabled() const;
    virtual void setCascadeOpacityEnabled(bool cascadeOpacityEnabled);
    virtual const Color3B& getColor(void) const;
    virtual const Color3B& getDisplayedColor() const;
    virtual void setColor(const Color3B& color);
    virtual void updateDisplayedColor(const Color3B& parentColor);
    virtual bool isCascadeColorEnabled() const;
    virtual void setCascadeColorEnabled(bool cascadeColorEnabled);

    void setFntFile(const char* fntFile);
    const char* getFntFile();
#if CC_LABELBMFONT_DEBUG_DRAW
    virtual void draw();
#endif // CC_LABELBMFONT_DEBUG_DRAW
private:
    char * atlasNameFromFntFile(const char *fntFile);
    int kerningAmountForFirst(unsigned short first, unsigned short second);
    float getLetterPosXLeft( Sprite* characterSprite );
    float getLetterPosXRight( Sprite* characterSprite );
    
protected:
    virtual void setString(unsigned short *newString, bool needUpdateLabel);
    // 给定的字符串
    unsigned short* _string;
    
    //  fntFile 的名字
    std::string _fntFile;
    
    // 初始字符串（没有换行）
    unsigned short* _initialString;
    std::string _initialStringUTF8;
    
    // 对齐所有行
    TextHAlignment _alignment;
    // 最大宽度知道添加一个换行符
    float _width;
    
    CCBMFontConfiguration *_configuration;
    
    bool _lineBreakWithoutSpaces;
    // texture atlas 的偏移量
    Point    _imageOffset;
    
    // 重用 char
    Sprite *_reusedChar;
    
    // texture RGBA
    GLubyte _displayedOpacity;
    GLubyte _realOpacity;
    Color3B _displayedColor;
    Color3B _realColor;
    bool _cascadeColorEnabled;
    bool _cascadeOpacityEnabled;
    /** 是否符合 RGBAProtocol 协议 */
    bool        _isOpacityModifyRGB;

};

/** 使用缓存解析一个 FNT 文件
*/
CC_DLL CCBMFontConfiguration * FNTConfigLoadFile( const char *file );
/** 清除 FNT 配置缓存
*/
CC_DLL void FNTConfigRemoveCache( void );

// end of GUI group
/// @}
/// @}

NS_CC_END

#endif //__CCBITMAP_FONT_ATLAS_H__