cocos2d-X 节点（CCLabelBMFont.h）API

cocos2d-X 节点（CCLabelBMFont.h）API

///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__