Reza Ghobadinic

Label

Reza Ghobadinic

Label is a type of Node class that can print text on the screen.

Creating Labels

There are three different ways to create labels by using:

System Fonts

You can make labels using the fonts that already exist in the system.

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

Example:

auto label_sys = Label::createWithSystemFont("This is a System font.", "Arial", 30.0);

True Type and Open Type Fonts

You can make labels using a path to a true type font (.ttf) or an open type font (.otf).

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

Examples:

I’ve downloaded a TTF and an OTF font from www.fontsquirrel.com for this test called Windsong.ttf and GreatVibes.otf. Remember to add these fonts to your project. In Xcode, I added them in Resources/fonts folder

auto label_ttf = Label::createWithTTF("This is a True Type font.", "fonts/Windsong.ttf", 30.0);
auto label_otf = Label::createWithTTF("This is an Open Type font.", "fonts/GreatVibes.otf", 30.0);

There is also another way to create labels using these font types and that is by creating a TTFConfig and using that to create the label. This is useful if you want to use the same preset for many labels across your game instead of typing them every time.

Example config variable:

TTFConfig config;
config.fontFilePath = "fonts/Windsong.ttf";
config.fontSize = 30;
config.outlineSize = 0;
config.distanceFieldEnabled = false;
config.glyphs = GlyphCollection::DYNAMIC;
config.customGlyphs = nullptr;

The create method for using the config variable is:

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

Example:

auto label_con = Label::createWithTTF(config, "Text Using Config.");

Bitmap Fonts

You can make labels using a path to a bitmap font (.fnt and .png). Bitmap fonts are the fastest to render and you should use then for whatever text that is inside the game itself to keep the higher game frame rate.

You can create your own bitmap font from any System, TTF or OTF font by using a program like Glyph Designer. When you make a bitmap font, you can decide what letters and symbols that font will include! You don’t have to use all letters and symbols, just the ones you need.

I’ve made one bitmap font before for my old Breakanator game. It is called ScoreBoardFont that I am adding to the example project. A bitmap font consists of two files. A .fnt and a .png file to be exact. The .png file keeps the rendered image of the font and the .fnt keeps the coordinates and the bounding box of the letters. One downside of using the bitmap fort is that you can’t change its size!

Format:

Label::createWithBMFont(const std::string &bmfontPath, const std::string &text);

Example:

auto label_bmp = Label::createWithBMFont("fonts/ScoreBoardFont.fnt", "This is a Bitmap font.");

Label Example

Lets put all these together and have a look at how it looks.

bool LabelScene::init()
{
    if ( !Scene::init() )
    {
        return false;
    }
    
    // Screen coordinates
    auto visibleSize = Director::getInstance()->getVisibleSize();   // Screen's visible size
    Vec2 origin = Director::getInstance()->getVisibleOrigin();      // Screen's visible origin
    float x = origin.x + visibleSize.width * 0.5;                   // X for the center of the screen
    
    // System Font
    auto label_sys = Label::createWithSystemFont("This is a System font.", "Arial", 30.0);
    label_sys->setPosition(x, 250);
    this->addChild(label_sys);
    
    // TTF Font
    auto label_ttf = Label::createWithTTF("This is a True Type font.", "fonts/Windsong.ttf", 30.0);
    label_ttf->setPosition(x, 200);
    this->addChild(label_ttf);
    
    // OTF Font
    auto label_otf = Label::createWithTTF("This is an Open Type font.", "fonts/GreatVibes.otf", 30.0);
    label_otf->setPosition(x, 150);
    this->addChild(label_otf);
    
    // Font Config
    TTFConfig config;
    config.fontFilePath = "fonts/Windsong.ttf";
    config.fontSize = 30;
    config.outlineSize  = 0;
    config.distanceFieldEnabled = false;
    config.glyphs = GlyphCollection::DYNAMIC;
    config.customGlyphs = nullptr;
    
    auto label_con = Label::createWithTTF(config, "This is a True Type font using TTFConfig.");
    label_con->setPosition(x, 100);
    this->addChild(label_con);
    
    // Bitmap Font
    auto label_bmp = Label::createWithBMFont("fonts/ScoreBoardFont.fnt", "This is a Bitmap font.");
    label_bmp->setPosition(x, 50);
    this->addChild(label_bmp);
    
    return true;
}

After build and run, you should see five labels printed in your screen.

Effects On Labels

For the system and ttf/otf fonts, there are some visual effects that we can apply to make them more interesting. Things like glow, drop shadow and outline.

Add these linesat the end of the init() method in the previous example and see the effects.

label_sys->enableOutline(Color4B::RED, 2);
label_ttf->enableShadow(Color4B::RED, Size(5,-5), 0);
label_otf->enableGlow(Color4B::RED);

Here is how the result looks now.

Accessing Letters On Bitmap Fonts

We can not use the font effects on a Bitmap Font label, but we can access its letters as sprites to make some of our own.

Now lets get the first letter of our Bitmap Font label and double it in size.

Again, you can add these to the end of the init() method in the previous example.

auto sprite1 = label_bmp->getLetter(0); // Get the first letter of the text
sprite1->setScale(2.0);                 // Scale it up by 2.0

See how the T in the last line is bigger now?

Download Source

Text Alignment

Multi line texts can have an alignment using one of these methods:

Each of these methods get an enum value for center, or side alignments:

To make multi line text, just insert “\n” in the middle of the text string between the lines.

Example:

auto label = Label::createWithSystemFont("First Line\nSecond Line\nThird Line", "Arial", 30);
label->setPosition(x, 200);
label->setHorizontalAlignment(TextHAlignment::CENTER);
this->addChild(label);
Exit mobile version