Skip to content
This repository was archived by the owner on Mar 11, 2021. It is now read-only.

Labels

Jump to bottom
Kenneth Pouncey edited this page Jul 7, 2015 · 30 revisions

Labels are used by the developer to present text to the user.

- Screen shot here

CocosSharp contains 4 types of Labels that can be used. (As of v1.4.0.0 CCLabelBMFont and CCLabelTtf are obsolete and replaced by CCLabel.)

CCLabel

As of version v1.4.0.0 of CocosSharp this label unifies the CCLabelTtf and CCLabelBMFont label types.

This label type allows for the use of Bitmap fonts, SpriteFonts and when a SystemFont is specified as the label type will use the platforms native graphics routines to draw and layout an image sprite.

Due to the inconsistencies of how all the different label types worked we have tried to unify all of the labels into one object CCLabel that provides as consistent an interface and functionality as possible.

The new unified label now sports a whole new set of constructors:

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    public CCLabel() { }
    
    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    public CCLabel(string str, string fntFile) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="labelFormat">Label format <see cref="CocosSharp.CCLabelFormat"/>.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions, CocosSharp.CCLabelFormat labelFormat) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="labelFormat">Label format <see cref="CocosSharp.CCLabelFormat"/>.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions, CocosSharp.CCLabelFormat labelFormat, CocosSharp.CCPoint imageOffset, CocosSharp.CCTexture2D texture) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="hAlignment">Horizontal alignment of the text.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions, CocosSharp.CCTextAlignment hAlignment) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="hAlignment">Horizontal alignment of the text.</param>
    /// <param name="vAlignement">Vertical alignement of the text.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions, CocosSharp.CCTextAlignment hAlignment, CocosSharp.CCVerticalTextAlignment vAlignement) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="hAlignment">Horizontal alignment of the text.</param>
    /// <param name="vAlignement">Vertical alignement of the text.</param>
    /// <param name="imageOffset">Image offset.</param>
    /// <param name="texture">Texture Atlas to be used.</param>
    public CCLabel(string str, string fntFile, CocosSharp.CCSize dimensions, CocosSharp.CCTextAlignment hAlignment, CocosSharp.CCVerticalTextAlignment vAlignment, CocosSharp.CCPoint imageOffset, CocosSharp.CCTexture2D texture) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    public CCLabel(string str, string fntFile, float size) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    /// <param name="labelFormat">Label format <see cref="CocosSharp.CCLabelFormat"/>.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCLabelFormat labelFormat) { 

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="labelFormat">Label format <see cref="CocosSharp.CCLabelFormat"/>.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCSize dimensions, CocosSharp.CCLabelFormat labelFormat) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="dimensions">Dimensions that the label should use to layout it's text.</param>
    /// <param name="labelFormat">Label format <see cref="CocosSharp.CCLabelFormat"/>.</param>
    /// <param name="imageOffset">Image offset.</param>
    /// <param name="texture">Texture atlas to be used.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCSize dimensions, CocosSharp.CCLabelFormat labelFormat, CocosSharp.CCPoint imageOffset, CocosSharp.CCTexture2D texture) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    /// <param name="alignment">Horizontal Alignment of the text.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCTextAlignment alignment) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    /// <param name="alignment">Horizontal Alignment of the text.</param>
    /// <param name="imageOffset">Image offset.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCTextAlignment alignment, CocosSharp.CCPoint imageOffset) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    /// <param name="alignment">Horizontal Alignment of the text.</param>
    /// <param name="imageOffset">Image offset.</param>
    /// <param name="texture">Texture Atlas to be used.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCTextAlignment alignment, CocosSharp.CCPoint imageOffset, CocosSharp.CCTexture2D texture) { }

    /// <summary>
    /// Initializes a new instance of the <see cref="CocosSharp.CCLabel"/> class.
    /// </summary>
    /// <param name="str">Initial text of the label.</param>
    /// <param name="fntFile">Font definition file to use.</param>
    /// <param name="size">Font point size.</param>
    /// <param name="hAlignment">Horizontal Alignment of the text.</param>
    /// <param name="vAlignment">Vertical alignment.</param>
    /// <param name="imageOffset">Image offset.</param>
    /// <param name="texture">Texture Atlas to be used.</param>
    public CCLabel(string str, string fntFile, float size, CocosSharp.CCTextAlignment hAlignment, CocosSharp.CCVerticalTextAlignment vAlignment, CocosSharp.CCPoint imageOffset, CocosSharp.CCTexture2D texture) { }

As you will notice there is a new parameter type that can be passed which is a CCLabelFormat. The CCLabelFormat specifies the type of label to create:

  • Unknown - Default type and when encountered will try to determine the label type automatically.
  • SpriteFont - Specifies a label that will be created will use a SpriteFont definition.
  • BitmapFont - Specifies a label that will be created will use a Bitmap Font definition.
  • CharacterMap - Not implemented at this time
  • SystemFont - Specifies a label that will be created will use a System defined font or .ttf that is included as content of the project.

The CCLabelFormat also has some predefined static definitions that can be used:

  • CCLabelFormat.SpriteFont
  • CCLabelFormat.BitmapFont
  • CCLabelFormat.SystemFont

If a CCLabelFormat is not passed to the CCLabel upon creation it will try to create the correct type of label by trying to create a label of each type until it finds one that was able to be created with the information provided. This is discouraged though as it does have some performance impact trying to load assets that do not exist so it is always better to try and create a label of the known type. If you have a lot of labels with specific formatting you can create a model CCLabelFormat that can be used as described below.

An example of using the CCLabelFormat is as follow:

// CCLabel Sprite Font
label1 = new CCLabel("Hello SpriteFont", "fonts/arial", 26, CCLabelFormat.SpriteFont);

// CCLabel Bitmap Font - No need to pass a CCLabelFormat because the default for this constructor is BitmapFont
label1 = new CCLabel("Hello Bitmap Font", "fonts/bitmapFontTest3.fnt");

// CCLabel using the system font Arial
label1 = new CCLabel("Hello System Font", "Arial", 20, CCLabelFormat.SystemFont);

// CCLabel using the MorrisRoman-Black.ttf font included as content in the fonts folder
label1 = new CCLabel("Hello MorrisRoman-Black", "fonts/MorrisRoman-Black.ttf", size, CCLabelFormat.SystemFont)

.ttf usage note: Developer needs to specify the .ttf file extension so that the CCLabel being created knows that special asset loading actions needs to be performed on different platforms.

Along with the Label type specification the CCLabelFormat also allows you to specify the following properties:

  • Alignment - A CCTextAlignment enumeration to specify the Horizontal text alignment when used with a constructor that takes a dimensions parameter or when the label's dimensions are set with the Dimensions property that define a width and height to be used for layout.
  • LineAlignment - A CCVerticalTextAlignment enumeration to specify the Vertical text alignment when used with a constructor that takes a dimensions parameter or when the label's dimensions are set with the Dimensions property that define a width and height to be used for layout.
  • LineBreaking - A CCLabelLineBreak enumeration of None, Character or Word that guides the text layout how to break text when used with a constructor that takes a dimensions parameter or when the label's dimensions are set with the Dimensions property that define a width and height to be used for layout.

Example use of creating a CCLabelFormat with specific attributes that can be passed to multiple CCLabel constructors.

// LabelFormat specifying horizontal and vertical layout alignments to centered.
var centeredLabelFormat = new CCLabelFormat(CCLabelFormatFlags.SpriteFont) { Alignment = CCTextAlignment.Center, LineAlignment = CCVerticalTextAlignment.Center };

// CCLabel Sprite Font using the centeredLabelFormat
label1 = new CCLabel("Hello SpriteFont", "fonts/arial", 26, centeredLabelFormat);

CCLabel SpriteFont support adds more flexibility than just the ability to change where the resource content is. They also add the flexibility of loading the resource without having to create them with the Font Size nomenclature that CCLabelTtf forces on the developer. Creating a CCLabel that uses a SpriteFont uses the naming convention of "Font Name" plus the "Font Size" so the resource name would need to be "arial-26.xnb" to find the correct one.

Example being:

// CCLabel Sprite Font that will look for SpriteFont1-26.xnb spritefont resource.
label1 = new CCLabel("Hello SpriteFont", "fonts/SpriteFont1", 26, CCLabelFormat.SpriteFont);

The previous example would look for a resource named "SpriteFont1-26.xnb" in the Content's "fonts" directory.

If the developer does not want to use this naming convention we now support passing 0 (Zero) as the font size and it will no longer try to load a SpriteFont resource named "SpriteFont1-0.xnb" but will look for "SpriteFont1.xnb" in the Content's "fonts" directory.

Example:

// CCLabel Sprite Font that will look for SpriteFont1.xnb spritefont resource.
label1 = new CCLabel("Hello SpriteFont", "fonts/SpriteFont1", 0, CCLabelFormat.SpriteFont);

The Unified Label also allows the developer to access individual characters of the labels Text field. Note that this only works for Bitmap and SpriteFont labels for now.

To access individual characters use the label's Indexer as follows:

		label = new CCLabel("Bitmap Font Atlas", "fonts/bitmapFontTest.fnt");
        AddChild(label);

		label.AnchorPoint = CCPoint.AnchorMiddle;


		var BChar = label[0];
		var FChar = label[7];
		var AChar = label[12];


		var rotate = new CCRotateBy (2, 360);
		var rot_4ever = new CCRepeatForever (rotate);

		var scale = new CCScaleBy(2, 1.5f);
		var scale_back = scale.Reverse();
		var scale_seq = new CCSequence(scale, scale_back);
		var scale_4ever = new CCRepeatForever (scale_seq);

        var jump = new CCJumpBy (0.5f, new CCPoint(), 60, 1);
        var jump_4ever = new CCRepeatForever (jump);

		var fade_out = new CCFadeOut  (1);
		var fade_in = new CCFadeIn  (1);
		var seq = new CCSequence(fade_out, fade_in);
		var fade_4ever = new CCRepeatForever (seq);

        BChar.RunAction(rot_4ever);
        BChar.RunAction(scale_4ever);
        FChar.RunAction(jump_4ever);
		AChar.RunAction(fade_4ever);

A complete program can be found in CocosSharp's test suite Using fonts as Sprite objects.

Limitations and differences from previous label types are:

  • Can not add children to the CCLabel
  • Use the CCLabel's Indexer property instead of relying on the label's Children. See example above.

The reason for the above mentioned limitations and differences is that we now have multiple label types unified into one and all trying to provide the same functionality. In the old label types for example CCLabelBMFont all children were sprites and using a CCSpriteBatchNode. The Unified Label no longer uses a CCSpriteBatchNode, instead opting to handle this internally allowing it to save on the memory of the sprites as well as the memory and processing used by CCSpriteBatchNode.

The only time that a sprite is now created is when it is specifically asked for i.e. by accessing it via the this[] Indexer. For example if the third character of a string is asked for then a sprite and associated memory will only be created for that one character. This allows developers that do not need this capability to not have that extra little memory allocated that a sprite uses. Nor the extra processing that is needed to coordinate the changes to the sprites. Once the sprite is asked for, it will be available to the Children of the CCLabel.

Pros

  • Now only one label type CCLabel and object.
  • Consistent interface defining labels.
  • Consistent look and feel when specifying AnchorPoints, Horizontal and Vertical Alignment etc. There admittedly have been problems with this in the past over the different labels that were provided.
  • It is very flexible. When a Bitmap Font or a SpriteFont is specified each letter of the label can be treated as it's own specific object. Thus you can attach CCActions to each character to create interesting effects. This does NOT work with System Fonts for now.
  • Bitmap and SpriteFont fonts are supported on all platforms.
  • Bitmap, SpriteFont and .TTF specified system fonts will use the defined ContentSearchPaths and ContentSearchResolutionOrder to identify and load the actual assets. In previous versions of the different incarnations of the labels this was not possible.
  • Bitmap and SpriteFont fonts support the specifying of custom LineHeight and AdditionalKernings.

Cons

  • Developer has to be careful because not all fonts exist on all platforms when using System Fonts. To have a consistent look and feel to your labels it is always better to use a Bitmap or SpriteFont font.
  • Developer has to be careful when using System Fonts as the native drawing routines of each platform does and will create fonts differently. This includes sizes as well so be fore warned.
  • If the developer decides to use a .TTF it will also need to be delivered along with the application and may have copyrights associated with them.
  • System fonts are NOT supported on Windows Phone 8.0 at this time.

- Screen shot here

CCLabelAtlas

This type of label uses a character map atlas to display it's text. The advantages of using this type of label is that it is fast but is not very flexible. This label has been superseded by CCLabelBMFont and is mostly used to maintain backwards compatibility. For instance CCStats.cs, for displaying the statistics, uses a CCLabelAtlas with an embedded image file.

This label type will also be obsolete in the future.

- Screen shot here

CCLabelBMFont

Marked obsolete as of release v1.4.0.0 - See CCLabel This type of label uses a Bitmap Font generated by an external program which consists of an image file and a character map configuration file.

  • The bitmap (image) can be customized with graphics editors.
  • The label can be updated without penalty. Internally the label uses a SpriteBatchNode so changing the text is just a matter of making the specific image of the character visible or not.
  • It is very flexible. Each letter of the label can be treated as it's own specific object. Thus you can attach CCActions to each character separately to create interesting effects.
  • Supports Kerning
  • Are only the size that the bitmap image was generated from and is not dynamic. This means if you want a specific font at 38 point size and 24 point size you will have to generate and include both with your application. You can of course try scaling the CCLabelBMFont and that might get you what you want.
  • Can be used on all supported platforms

- Screen shot here

CCLabelTtf

Marked obsolete as of release v1.4.0.0 - See CCLabel Even though this type of label hints at being a label that displays .TTF (True Type Fonts) it actually does not have anything to do with TTF at all. This label type is a wrapper around an XNA/MonoGame spritefont resource.

  • Can use the numerous .xnb spritefont resources that can be found on the internet.
  • Can create your own using the XNA Content Pipeline or MonoGames Gui Content Pipeline with the caveat that these are unfortunately Windows only for now. MonoGame has an experimental Mac version as well.
  • Sometimes difficult to use. For instance iOS has to be generated differently than the other platforms due to the way the underlying image needs to be presented to the platform.
  • Supports Kerning
  • Are only the size that the spritefont specifies and is not dynamic. This means if you want a specific font at 38 point size and 24 point size you will have to generate and include both in your package. You can of course try scaling the CCLabelTtf and that might get you what you want.
  • Can be used on all supported platforms.

- Screen shot here

Clone this wiki locally