Cocos2d-x study notes (18) Label

1 Introduction

Label the direct successor to the Node LabelProtocol BlendProtocol, for rendering text, so that the effect of rich text rendering.

Label There are four types:

    enum class LabelType {
        TTF,
        BMFONT,
        CHARMAP,
        STRING_TEXTURE
    };

Label text rendering effects:

enum class LabelEffect {
    NORMAL,
    OUTLINE,
    SHADOW,
    GLOW,
    ITALICS,
    BOLD,
    UNDERLINE,
    STRIKETHROUGH,
    ALL
};

For four kinds of operation when the text length Label size range conflicts with enumeration defines:

    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
    };

 

1

2. Constructor

We learned from the constructor:

Anchor (0.5, 0.5)

Call reset () method

LabelType default STRING_TEXTURE

LabelEffect default NORMAL

Set the default font and size

label length and width of the size of the default 0

Alignment default LEFT TOP

Text color default white, the effect of the default black color

Overflow default NONE 

3. create

create()

Create an empty label objects and pointers.

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)

A total of six parameters:

• string & text string to display
• string & font font, the font name / font file
• float fontSize font size must be greater than 0
• Size& dimensions = Size::ZERO label大小，默认Size(0, 0)
• TextHAlignment hAlignment = TextHAlignment :: LEFT horizontal alignment, the default left-aligned
• TextVAlignment vAlignment = TextVAlignment :: TOP vertical alignment, top alignment default

achieve:

    auto right = new (std :: nothrow) Label (HAlignment, VAlignment);
    if (right) 
    { 
        right -> setSystemFontName (font); 
        right -> setSystemFontSize (FontSize); 
        right -> setDimensions (dimensions.width, dimensions.height); 
        right -> setString (Text); 

        right -> autorelease (); 

        Return the right; 
    } 
    Return nullptr;

It is set with parameters set method.

• setSystemFontName
  _systemFont set parameters font
  _currentLabelType = LabelType :: STRING_TEXTURE
  _systemFontDirty to true =
  
  
• setSystemFontSize　
  _systemFontSize _originalFontSize parameters set the font size
  _currentLabelType = LabelType :: STRING_TEXTURE;
  _systemFontDirty to true =　　
  
  
• setDimensions
  If Overflow is RESIZE_HEIGHT type, the first parameter set height 0
  

  _labelWidth = width;
  _labelHeight = height;
  _labelDimensions.width = width;
  _labelDimensions.height = height;
  _maxLineWidth = width; //最大文本宽度

  _contentDirty = true;
  
  if Overflow is SHRINK type,

  　　if (_originalFontSize > 0) {
            this->restoreFontSize();
        }

• the setString
  _utf8Text _utf32Text stores a set of strings

createWithTTF

There are two overloaded methods:

• Method 1: Parameters specified string with string & fontFilePath font file path .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)

  No parameters ttf, generated using the parameters corresponding to ttf, after calling the setTTFConfig (ttfConfig)
  also called setDimensions (dimensions.width, dimensions.height); setString (text);

• Method 2: by setting font parameters TTFConfig, maxLineWidth text line width of the maximum value (default 0 represents not set)
  

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

　　  TtfConfig parameter called setTTFConfig (ttfConfig), after performing setMaxLineWidth (maxLineWidth); setString (text);

TTFConfig is a font configuration structure:

typedef struct _ttfConfig 
{ 
    std :: String fontFilePath; // font file path, default empty 
    float fontSize; // font size, default 12 

    GlyphCollection Glyphs; // character set, by default the DYNAMIC 
    const  char * customGlyphs; // custom character set, no default 

    BOOL distanceFieldEnabled; // if the font is compact, default false 
    int outlineSize; // font outline size, default 0 

    BOOL italics; // italic, default false 
    BOOL Bold; // whether bold, default false 
    BOOL underline; //Whether underlined, default false 
    BOOL strikethrough; // Is there strikethrough, default false 

    _ttfConfig ( .......... ) 
        : fontFilePath (filePath) 
        , fontSize (size) 
        , Glyphs (glyphCollection) 
        , customGlyphs (customGlyphCollection ) 
        , distanceFieldEnabled (useDistanceField) 
        , outlineSize (Outline) 
        , Italics (useItalics) 
        , Bold (useBold) 
        , underline (useUnderline) 
        , strikethrough (useStrikethrough) 
    { 
        IF (Outline> 0 ) 
        { 
            distanceFieldEnabled = to false;
        }
    }
} TTFConfig;

setTTFConfig(ttfConfig)

First execution _originalFontSize = ttfConfig.fontSize

Then call setTTFConfigInternal (ttfConfig)

_currentLabelType = LabelType::TTF

createWithBMFont

.Fnt parameters include a file path and BMFont software-generated text displayed. Text strings must be defined and .fnt file, or it does not show excess.

Label* createWithBMFont(const std::string& bmfontPath, const std::string& text,
        const TextHAlignment& hAlignment = TextHAlignment::LEFT, int maxLineWidth = 0,
        const Vec2& imageOffset = Vec2::ZERO)

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

Call setMaxLineWidth (maxLineWidth) setString (text);

We use BMFont can generate custom fonts, font software export .fnt font information files, and .png image file, two files in the same directory is used Cocos2dx.

createWithCharMap

There are three overloaded methods:

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)

Creating divided into three types:

• By .png image files
• By Texture2D texture
• By .plist file

The first two ways to set the parameters in each panel represent the length and width of the character, the starting index value startCharMap (ASCII, with '0' instead of 48). .plist is already included these parameters.

Each call to reload all the corresponding setCharMap, which calls the corresponding FontAtlasCache :: getFontAtlasCharMap generate newAtlas, then perform

　　_currentLabelType = LabelType::CHARMAP
　　setFontAtlas(newAtlas)

- TTF BMFont CharMap

TTF font attributes unified configuration, all the text on the label are valid.

BMFont need .fnt .png file, only necessary to use .fnt path, .fnt .plist similar, selection of characters corresponding to enlarge .png by text.

CharMap can be seen as a simplified version of BMFont reads big picture in a different character by ASCII.

4. rendering effects

Label offers three font effects:

• Shadow Shadow
• Outline Stroke
• Glow luminescent

Three kinds of effects settings ways:

enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0)
enableOutline(const Color4B& outlineColor,int outlineSize = -1)
enableGlow(const Color4B& glowColor)

Outline Stroke and luminous Glow only support label createWithTTF created. When both are used, and only after setting display.

Shadow Shadow's Size label the upper left corner of the shadow of the setting position as a reference point.

5. Alignment

Label default alignment is LEFT + TOP.

Divided into horizontal and vertical directions, corresponding to the two members Label:

    _HAlignment TextHAlignment; // horizontal 
    TextVAlignment _vAlignment; // vertical

Define two enumeration:

enum class CC_DLL TextVAlignment
{
    TOP,
    CENTER,
    BOTTOM
};

enum class CC_DLL TextHAlignment
{
    LEFT,
    CENTER,
    RIGHT
};

Related set get method:

    void setAlignment (TextHAlignment hAlignment) {setAlignment (hAlignment, _vAlignment);} 
    TextHAlignment getTextAlignment () const { return _hAlignment;}
     void setAlignment (TextHAlignment hAlignment, TextVAlignment vAlignment); 

    void setHorizontalAlignment (TextHAlignment hAlignment) {setAlignment (hAlignment, _vAlignment); } 
    TextHAlignment getHorizontalAlignment () const { return _hAlignment; } 

    Void setVerticalAlignment (TextVAlignment vAlignment) {setAlignment (_hAlignment, vAlignment); } 
    TextVAlignment getVerticalAlignment () const { return _vAlignment; }

6. size range

Text box in which the size of label, to the variable:

    Size _labelDimensions;
    float _labelWidth;
    float _labelHeight;

Related get set method:

    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;}

Set the size using setDimensions, instead of Node setContentSize. setDimensions main logic:

_labelWidth = width;
_labelHeight = height;
_labelDimensions.width = width;
_labelDimensions.height = height;
_maxLineWidth = width;

-

7. The color of the text font size

    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. Wrap pitch trekking

- void setLineBreakWithoutSpace(bool breakWithoutSpace)

Wrap feature is turned on, set the property _lineBreakWithoutSpaces.

- void setMaxLineWidth(float maxLineWidth)

Set the maximum line width, it is necessary to continue _labelWidth is set to 0, otherwise we will be able to achieve only wrap by _labelWidth. A property _maxLineWidth.

- label size-dependent

It involves _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()

Directly modify the properties _lineHeight. Line spacing is not supported by System Font.

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

Character Spacing modify the properties _additionalKerning, do not support the System Font.

-