FlixelText

View source

class

org.flixelgdx.text.FlixelText

public class FlixelText extends FlixelSprite

A display object for rendering text on screen.

Extends FlixelSprite so that text objects can be added to sprite groups and states, with full support for tinting, fading, rotation, and scaling. Uses libGDX's BitmapFont for rendering and optionally FreeTypeFontGenerator for dynamic font generation from .ttf/.otf files.

Auto-sizing

By default, FlixelText auto-sizes to fit its text content. To use a fixed width, pass a positive fieldWidth to the constructor or call FlixelText.setFieldWidth(float). A fixed height can be set via FlixelText.setFieldHeight(float).

Fonts

The default font is libGDX's built-in bitmap font (Arial 15px), scaled to the requested size. For best quality at any size, supply a .ttf or .otf file via FlixelText.setFont(FileHandle), which uses FreeType to generate a crisp bitmap font at the exact pixel size requested.

Border Styles

Text can be rendered with borders via FlixelText.setBorderStyle(...). Supported styles are BorderStyle.SHADOW, BorderStyle.OUTLINE, and BorderStyle.OUTLINE_FAST.

Sprite Methods

Graphic-loading methods inherited from FlixelSprite are not applicable to text and will throw UnsupportedOperationException if called.

Constructors

FlixelText()

public FlixelText()

Creates a new text object at (0, 0) with default settings.

---

FlixelText(float, float)

public FlixelText(float x, float y)

Creates a new text object at the specified position.

Parameters:

Name	Description
x	The x position of the text.
y	The y position of the text.

---

FlixelText(float, float, float)

public FlixelText(float x, float y, float fieldWidth)

Creates a new text object at the specified position with a field width.

Parameters:

Name	Description
x	The x position of the text.
y	The y position of the text.
fieldWidth	The width of the text field. Auto-sizes if <= 0.

---

FlixelText(float, float, float, String)

public FlixelText(float x, float y, float fieldWidth, String text)

Creates a new text object with position, field width, and initial text.

Parameters:

Name	Description
x	The x position of the text.
y	The y position of the text.
fieldWidth	The width of the text field. Auto-sizes if <= 0.
text	The text to display initially.

---

FlixelText(float, float, float, String, int)

public FlixelText(float x, float y, float fieldWidth, String text, int size)

Creates a new text object with all primary parameters.

Parameters:

Name	Description
x	The x position of the text.
y	The y position of the text.
fieldWidth	The width of the text field. Auto-sizes if <= 0.
text	The text to display initially.
size	The font size in pixels.

---

Methods

getTextBuffer()

public FlixelString getTextBuffer()

Returns the text currently being displayed.

---

getText()

public String getText()

Gets the string version of the text being displayed for this text object.

Note that you should not call this every frame. If you must get the texting being displayed of your text object, use FlixelText.getTextBuffer() instead, paired with FlixelStringUtil.contentEquals(CharSequence, CharSequence) for comparisons.

Returns: The string version of the text being displayed on this text object.

---

setText(String)

public void setText(String text)

Sets the text to display.

Parameters:

Name	Description
text	The new text string.

---

setText(CharSequence)

public void setText(CharSequence text)

Sets the display text of this text object using a native Java CharSequence.

Parameters:

Name	Description
text	The CharSequence to apply to this text object. For most FlixelGDX games this is typically a FlixelString.

---

getTextSize()

public int getTextSize()

Returns the font size in pixels.

---

setTextSize(int)

public void setTextSize(int size)

Sets the font size in pixels. When using a FreeType font, this triggers font regeneration. When using the default font, the built-in bitmap font is scaled.

Parameters:

Name	Description
size	The new font size (minimum 1).

---

getAlignment()

public Alignment getAlignment()

Returns the current text alignment.

---

setAlignment(Alignment)

public void setAlignment(Alignment alignment)

Sets the horizontal alignment of the text within the field. Only has a visible effect when FlixelText.isAutoSize() is false (i.e. the field has a fixed width).

Parameters:

Name	Description
alignment	The alignment to use.

---

isWordWrap()

public boolean isWordWrap()

Returns whether word wrapping is enabled.

---

getWordWrap()

public boolean getWordWrap()

Returns whether word wrapping is enabled.

---

setWordWrap(boolean)

public void setWordWrap(boolean wordWrap)

Enables or disables word wrapping. Defaults to true.

Parameters:

Name	Description
wordWrap	Whether to wrap text at the field width.

---

isAutoSize()

public boolean isAutoSize()

Returns whether the text field auto-sizes to fit its content.

---

getAutoSize()

public boolean getAutoSize()

Returns whether the text field auto-sizes to fit its content.

---

setAutoSize(boolean)

public void setAutoSize(boolean autoSize)

Sets whether the text field auto-sizes to fit content. When true, FlixelText.getFieldWidth() and FlixelText.getFieldHeight() are determined automatically. Requires FlixelText.isWordWrap() to be false to take full effect.

Parameters:

Name	Description
autoSize	Whether to auto-size.

---

getFieldWidth()

public float getFieldWidth()

Returns the width of the text field, or 0 if auto-sizing.

---

setFieldWidth(float)

public void setFieldWidth(float fieldWidth)

Sets the width of the text field. A positive value disables auto-sizing so the hitbox and layout use this fixed width; a value <= 0 re-enables auto-sizing so dimensions are derived from the text content.

Parameters:

Name	Description
fieldWidth	The field width in pixels.

---

getFieldHeight()

public float getFieldHeight()

Returns the height of the text field, or 0 if auto-height.

---

setFieldHeight(float)

public void setFieldHeight(float fieldHeight)

Sets the height of the text field. When <= 0, height is determined automatically from the text content. Has no effect when FlixelText.isAutoSize() is true.

Parameters:

Name	Description
fieldHeight	The field height in pixels.

---

isBold()

public boolean isBold()

Returns whether bold text is enabled.

---

getBold()

public boolean getBold()

Returns whether bold text is enabled.

---

setBold(boolean)

public void setBold(boolean bold)

Sets whether to use bold text. Only takes visual effect when a .ttf font has been set via FlixelText.setFont(FileHandle), since the default bitmap font does not support runtime weight changes.

Parameters:

Name	Description
bold	Whether to use bold.

---

isItalic()

public boolean isItalic()

Returns whether italic text is enabled.

---

getItalic()

public boolean getItalic()

Returns whether italic text is enabled.

---

setItalic(boolean)

public void setItalic(boolean italic)

Sets whether to use italic text. Only takes visual effect when a .ttf font has been set via FlixelText.setFont(FileHandle), since the default bitmap font does not support runtime style changes.

Parameters:

Name	Description
italic	Whether to use italic.

---

getLetterSpacing()

public float getLetterSpacing()

Returns the letter spacing in pixels.

---

setLetterSpacing(float)

public void setLetterSpacing(float letterSpacing)

Sets the spacing between characters in pixels. Only takes visual effect when a .ttf font has been set via FlixelText.setFont(FileHandle), as FreeType uses this value during glyph generation.

Parameters:

Name	Description
letterSpacing	The spacing in pixels.

---

isEmbedded()

public boolean isEmbedded()

Returns whether this text uses a custom embedded font (true) or the default libGDX bitmap font (false). A font is considered embedded when set via FlixelText.setFont(FileHandle), FlixelText.setFont(String), or when a registry default is active.

---

getEmbedded()

public boolean getEmbedded()

Returns whether this text uses a custom embedded font (true) or the default libGDX bitmap font (false). A font is considered embedded when set via FlixelText.setFont(FileHandle), FlixelText.setFont(String), or when a registry default is active.

---

getFont()

public String getFont()

Returns the FlixelFontRegistry ID currently set on this text, or null if a direct FileHandle or the default font is used.

---

setFont(String)

public void setFont(String id)

Sets the font by its FlixelFontRegistry identifier.

The font must have been previously registered via FlixelFontRegistry.register(String, FileHandle). Pass null to clear the registry reference and fall back to the default resolution order (direct file -> registry default -> built-in font).

Parameters:

Name	Description
id	The registered font ID, or null to clear.

Throws:

Type	Description
IllegalArgumentException	if id is non-null but not registered.

---

setFont(FileHandle)

public void setFont(FileHandle fontFile)

Sets a custom TrueType font file for this text. Uses FreeType to generate a bitmap font at the current size. Pass null to revert to the default font. This clears any previously set registry ID.

Parameters:

Name	Description
fontFile	The .ttf or .otf file handle, or null.

---

setBitmapFont(BitmapFont)

public void setBitmapFont(BitmapFont font)

Sets a pre-built BitmapFont directly, bypassing FreeType generation. This gives full control over font settings. The caller is responsible for the font's lifecycle if this text is destroyed or the font is replaced. Clears any previously set font file or registry ID.

Parameters:

Name	Description
font	The bitmap font to use. Must not be null.

Throws:

Type	Description
IllegalArgumentException	if font is null.

---

getBorderStyle()

public BorderStyle getBorderStyle()

Returns the current border style.

---

getBorderColor()

public Color getBorderColor()

Returns the border color.

---

getBorderSize()

public float getBorderSize()

Returns the border size in pixels.

---

getBorderQuality()

public float getBorderQuality()

Returns the border rendering quality.

---

setBorderStyle(BorderStyle, Color, float, float)

public void setBorderStyle(BorderStyle style, Color color, float size, float quality)

Sets the border style, color, size, and quality in one call.

Parameters:

Name	Description
style	The border style.
color	The border color in RGBA. Pass null for transparent.
size	The border size in pixels.
quality	Rendering quality. 0: single iteration, 1: one iteration per pixel in size.

---

setBorderStyle(BorderStyle, Color)

public void setBorderStyle(BorderStyle style, Color color)

Sets the border style and color with default size (1) and quality (1).

Parameters:

Name	Description
style	The border style.
color	The border color.

---

setBorderStyle(BorderStyle, FlixelColor)

public void setBorderStyle(BorderStyle style, FlixelColor color)

Sets the border style and color with default size (1) and quality (1).

Parameters:

Name	Description
style	The border style.
color	The border color.

---

setBorderStyle(BorderStyle, FlixelColor, float, float)

public void setBorderStyle(BorderStyle style, FlixelColor color, float size, float quality)

Sets the border style, color, size, and quality in one call.

Parameters:

Name	Description
style	The border style.
color	The border color. Pass null for transparent.
size	The border size in pixels.
quality	Rendering quality. 0: single iteration, 1: one iteration per pixel in size.

---

setBorderStyle(BorderStyle)

public void setBorderStyle(BorderStyle style)

Sets the border style with a default black color, size of 1, and quality of 1.

Parameters:

Name	Description
style	The border style.

---

setFormat(FileHandle, int, Color, Alignment, BorderStyle, Color)

public void setFormat(FileHandle fontFile, int size, Color color, Alignment alignment, BorderStyle borderStyle, Color borderColor)

Convenience method to set many text properties at once. Pass null or 0 for any parameter to keep its current value.

Parameters:

Name	Description
fontFile	The .ttf/.otf font file, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.
alignment	The text alignment, or null to keep current.
borderStyle	The border style, or null to keep current.
borderColor	The border color, or null to keep current.

---

setFormat(FileHandle, int, Color)

public void setFormat(FileHandle fontFile, int size, Color color)

Simplified format setter with font file, size, and color.

Parameters:

Name	Description
fontFile	The font file, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

setFormat(FileHandle, int, FlixelColor, Alignment, BorderStyle, FlixelColor)

public void setFormat(FileHandle fontFile, int size, FlixelColor color, Alignment alignment, BorderStyle borderStyle, FlixelColor borderColor)

Convenience method to set many text properties at once using a FlixelColor. Pass null or 0 for any parameter to keep its current value.

Parameters:

Name	Description
fontFile	The .ttf/.otf font file, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.
alignment	The text alignment, or null to keep current.
borderStyle	The border style, or null to keep current.
borderColor	The border color, or null to keep current.

---

setFormat(FileHandle, int, FlixelColor)

public void setFormat(FileHandle fontFile, int size, FlixelColor color)

Simplified format setter with font file, size, and a FlixelColor.

Parameters:

Name	Description
fontFile	The font file, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

setFormat(String, int, Color, Alignment, BorderStyle, Color)

public void setFormat(String fontId, int size, Color color, Alignment alignment, BorderStyle borderStyle, Color borderColor)

Convenience format setter using a FlixelFontRegistry font ID. Pass null for any parameter to keep its current value.

Parameters:

Name	Description
fontId	The registered font ID, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.
alignment	The text alignment, or null to keep current.
borderStyle	The border style, or null to keep current.
borderColor	The border color, or null to keep current.

---

setFormat(String, int, Color)

public void setFormat(String fontId, int size, Color color)

Simplified format setter with a registry font ID, size, and color.

Parameters:

Name	Description
fontId	The registered font ID, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

setFormat(String, int, FlixelColor, Alignment, BorderStyle, FlixelColor)

public void setFormat(String fontId, int size, FlixelColor color, Alignment alignment, BorderStyle borderStyle, FlixelColor borderColor)

Convenience format setter using a FlixelFontRegistry font ID and a FlixelColor. Pass null or 0 for any parameter to keep its current value.

Parameters:

Name	Description
fontId	The registered font ID, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.
alignment	The text alignment, or null to keep current.
borderStyle	The border style, or null to keep current.
borderColor	The border color, or null to keep current.

---

setFormat(String, int, FlixelColor)

public void setFormat(String fontId, int size, FlixelColor color)

Simplified format setter with a registry font ID, size, and a FlixelColor.

Parameters:

Name	Description
fontId	The registered font ID, or null to keep current.
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

setFormat(int, Color)

public void setFormat(int size, Color color)

Simplified format setter with size and color only.

Parameters:

Name	Description
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

setFormat(int, FlixelColor)

public void setFormat(int size, FlixelColor color)

Simplified format setter with size and a FlixelColor only.

Parameters:

Name	Description
size	The font size, or 0 to keep current.
color	The text color, or null to keep current.

---

getWidth()

public float getWidth()

Returns the hitbox width, triggering a layout rebuild first if any text attributes have changed since the last rebuild.

This ensures that callers such as FlixelText.screenCenter() always operate on up-to-date dimensions, even before the first FlixelText.draw(FlixelBatch) call.

If no font is available yet (for example, before a GL context exists), the returned value is 0 until the first successful rebuild.

---

getHeight()

public float getHeight()

Returns the hitbox height, triggering a layout rebuild first if any text attributes have changed since the last rebuild.

This ensures that callers such as FlixelText.screenCenter() always operate on up-to-date dimensions, even before the first FlixelText.draw(FlixelBatch) call.

If no font is available yet (for example, before a GL context exists), the returned value is 0 until the first successful rebuild.

---

getTextWidth()

public float getTextWidth()

Returns the actual rendered width of the text content (which may differ from FlixelText.getFieldWidth() when a fixed field width is set). Triggers a layout rebuild if necessary.

---

getTextHeight()

public float getTextHeight()

Returns the actual rendered height of the text content (which may differ from FlixelText.getFieldHeight() when a fixed field height is set). Triggers a layout rebuild if necessary.

---

update(float)

public final void update(float elapsed)

Text objects do not use frame-based animation. This override prevents the animation state machine in FlixelSprite from running.

---

draw(FlixelBatch)

public void draw(FlixelBatch batch)

---

setAntialiasing(boolean)

public void setAntialiasing(boolean antialiasing)

---

loadGraphic(FileHandle)

public final FlixelSprite loadGraphic(FileHandle path)

Throws:

Type	Description
UnsupportedOperationException	always; text objects cannot load graphics.

---

loadGraphic(FileHandle, int)

public final FlixelSprite loadGraphic(FileHandle path, int frameWidth)

Throws:

Type	Description
UnsupportedOperationException	always; text objects cannot load graphics.

---

loadGraphic(FileHandle, int, int)

public final FlixelSprite loadGraphic(FileHandle path, int frameWidth, int frameHeight)

Throws:

Type	Description
UnsupportedOperationException	always; text objects cannot load graphics.

---

loadGraphic(Texture, int, int)

public final FlixelSprite loadGraphic(Texture texture, int frameWidth, int frameHeight)

Throws:

Type	Description
UnsupportedOperationException	always; text objects cannot load graphics.

---

applySparrowAtlas(FlixelGraphic, Array<FlixelFrame>)

public final void applySparrowAtlas(FlixelGraphic newGraphic, Array<FlixelFrame> parsedFrames)

Throws:

Type	Description
UnsupportedOperationException	always; text objects cannot use Sparrow atlases.

---

getAtlasRegions()

public final Array<FlixelFrame> getAtlasRegions()

Returns: null always; text has no atlas regions.

---

getCurrentFrame()

public final FlixelFrame getCurrentFrame()

Returns: null always; text has no animation frames.

---

getFrames()

public final FlixelFrame[][] getFrames()

Returns: null always; text has no image frames.

---

destroy()

public void destroy()

---

toString()

public String toString()

---

Alignment

enum

org.flixelgdx.text.FlixelText.Alignment

public static final enum Alignment

Horizontal alignment options for text within its field.

Fields

LEFT

public static final Alignment LEFT

---

CENTER

public static final Alignment CENTER

---

RIGHT

public static final Alignment RIGHT

---

Methods

values()

public static Alignment[] values()

---

valueOf(String)

public static Alignment valueOf(String name)

---

fromInt(int)

public static Alignment fromInt(int value)

---

toInt()

public int toInt()

---

toGdxAlign()

public int toGdxAlign()

---

BorderStyle

enum

org.flixelgdx.text.FlixelText.BorderStyle

public static final enum BorderStyle

Border/outline styles for text rendering.

Fields

NONE

public static final BorderStyle NONE

No border.

---

SHADOW

public static final BorderStyle SHADOW

A simple drop-shadow offset below and to the right of the text.

---

OUTLINE

public static final BorderStyle OUTLINE

A full outline drawn in all 8 directions around each glyph.

---

OUTLINE_FAST

public static final BorderStyle OUTLINE_FAST

A faster outline using only the 4 cardinal directions.

---

Methods

values()

public static BorderStyle[] values()

---

valueOf(String)

public static BorderStyle valueOf(String name)

---