Package com.jme3.font

Class BitmapText

java.lang.Object
com.jme3.scene.Spatial
com.jme3.scene.Node
com.jme3.font.BitmapText
All Implemented Interfaces:
HasLocalTransform, CloneableSmartAsset, Collidable, Savable, JmeCloneable, Cloneable
public class BitmapText extends Node
`BitmapText` is a spatial node that displays text using a BitmapFont. It handles text layout, alignment, wrapping, coloring, and styling based on the properties set via its methods. The text is rendered as a series of quads (rectangles) with character textures from the font's pages.

  • Constructor Details

    • BitmapText

      public BitmapText(BitmapFont font)
      Creates a new `BitmapText` instance using the specified font. The text will be rendered left-to-right by default, unless the font itself is configured for right-to-left rendering.
      Parameters:
      font - The BitmapFont to use for rendering the text (not null).

    • BitmapText

      @Deprecated public BitmapText(BitmapFont font, boolean rightToLeft)
      Deprecated.
      The "rightToLeft" flag should be specified in the font. Use BitmapText(com.jme3.font.BitmapFont)
      Parameters:
      font - the font to use (not null, alias created)
      rightToLeft - true → right-to-left, false → left-to-right (default=false)

    • BitmapText

      public BitmapText(BitmapFont font, boolean rightToLeft, boolean arrayBased)
      Creates a new `BitmapText` instance with the specified font, text direction, and a flag for array-based rendering.
      Parameters:
      font - The BitmapFont to use for rendering the text (not null).
      rightToLeft - true for right-to-left text rendering, false for left-to-right.
      arrayBased - If true, the internal text pages will use array-based buffers for rendering. This might affect performance or compatibility depending on the renderer.

  • Method Details

    • clone

      public BitmapText clone()
      Description copied from interface: CloneableSmartAsset
      Creates a clone of the asset. Please see Object.clone() for more info on how this method should be implemented.
      Specified by:
      clone in interface CloneableSmartAsset
      Overrides:
      clone in class Spatial
      Returns:
      A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated.
      See Also:

    • cloneFields

      public void cloneFields(Cloner cloner, Object original)
      Called internally by com.jme3.util.clone.Cloner. Do not call directly.
      Specified by:
      cloneFields in interface JmeCloneable
      Overrides:
      cloneFields in class Node
      Parameters:
      cloner - The cloner that is performing the cloning operation. The cloneFields method can call back into the cloner to make clones of its subordinate fields.
      original - The original object from which this object was cloned. This is provided for the very rare case that this object needs to refer to its original for some reason. In general, all of the relevant values should have been transferred during the shallow clone, and this object need only clone what it wants.

    • getFont

      public BitmapFont getFont()
      Returns the BitmapFont currently used by this `BitmapText` instance.
      Returns:
      The BitmapFont object.

    • setSize

      public void setSize(float size)
      Sets the size of the text. This value scales the font's base character sizes.
      Parameters:
      size - The desired text size (e.g., in world units or pixels).

    • getSize

      public float getSize()
      Returns the current size of the text.
      Returns:
      The text size.

    • setText

      public void setText(CharSequence text)
      Sets the text content to be displayed.
      Parameters:
      text - The `CharSequence` (e.g., `String` or `StringBuilder`) to display. If null, the text will be set to an empty string.

    • setText

      public void setText(String text)
      Sets the text content to be displayed. If the new text is the same as the current text, no update occurs. Otherwise, the internal `StringBlock` and `Letters` objects are updated, and a refresh is flagged to re-layout the text.
      Parameters:
      text - The `String` to display. If null, the text will be set to an empty string.

    • getText

      public String getText()
      Returns the current text content displayed by this `BitmapText` instance.
      Returns:
      The text content as a `String`.

    • getColor

      public ColorRGBA getColor()
      Returns the base color applied to the entire text. Note: Substring colors set via `setColor(int, int, ColorRGBA)` or `setColor(String, ColorRGBA)` will override this base color for their respective ranges.
      Returns:
      The base ColorRGBA of the text.

    • setColor

      public void setColor(ColorRGBA color)
      Sets the base color for the entire text. This operation will clear any previously set substring colors.
      Parameters:
      color - The new base ColorRGBA for the text.

    • setAlpha

      public void setAlpha(float alpha)
      Sets an overall alpha (transparency) value that will be applied to all letters in the text. If the alpha passed is -1, the alpha reverts to its default behavior: 1.0 for unspecified parts, and the encoded alpha from any color tags.
      Parameters:
      alpha - The desired alpha value (0.0 for fully transparent, 1.0 for fully opaque), or -1 to revert to default alpha behavior.

    • getAlpha

      public float getAlpha()
      Returns the current base alpha value applied to the text.
      Returns:
      The base alpha value, or -1 if default alpha behavior is active.

    • setBox

      public void setBox(Rectangle rect)
      Defines a rectangular bounding box within which the text will be rendered. This box is used for text wrapping and alignment.
      Parameters:
      rect - The Rectangle defining the position (x, y) and size (width, height) of the text rendering area.

    • getLineHeight

      public float getLineHeight()
      Returns the height of a single line of text, scaled by the current text size.
      Returns:
      The calculated line height.

    • getHeight

      public float getHeight()
      Calculates and returns the total height of the entire text block, considering all lines and the defined text box (if any).
      Returns:
      The total height of the text block.

    • getLineWidth

      public float getLineWidth()
      Calculates and returns the maximum width of any line in the text block.
      Returns:
      The maximum line width of the text.

    • getLineCount

      public int getLineCount()
      Returns the number of lines the text currently occupies.
      Returns:
      The total number of lines.

    • getLineWrapMode

      public LineWrapMode getLineWrapMode()
      Returns the current line wrapping mode set for this text.
      Returns:
      The LineWrapMode enum value.

    • setAlignment

      public void setAlignment(BitmapFont.Align align)
      Sets the horizontal alignment for the text within its bounding box. This is only applicable if a text bounding box has been set using setBox(Rectangle).
      Parameters:
      align - The desired horizontal alignment (e.g., BitmapFont.Align.Left, BitmapFont.Align.Center, BitmapFont.Align.Right).
      Throws:
      RuntimeException - If a bounding box is not set and `align` is not `Align.Left`.

    • setVerticalAlignment

      public void setVerticalAlignment(BitmapFont.VAlign align)
      Sets the vertical alignment for the text within its bounding box. This is only applicable if a text bounding box has been set using setBox(Rectangle).
      Parameters:
      align - The desired vertical alignment (e.g., BitmapFont.VAlign.Top, BitmapFont.VAlign.Center, BitmapFont.VAlign.Bottom).
      Throws:
      RuntimeException - If a bounding box is not set and `align` is not `VAlign.Top`.

    • getAlignment

      public BitmapFont.Align getAlignment()
      Returns the current horizontal alignment set for the text.
      Returns:
      The current BitmapFont.Align value.

    • getVerticalAlignment

      public BitmapFont.VAlign getVerticalAlignment()
      Returns the current vertical alignment set for the text.
      Returns:
      The current BitmapFont.VAlign value.

    • setStyle

      public void setStyle(int start, int end, int style)
      Sets the font style for a specific substring of the text. If the font does not contain the specified style, the default style will be used.
      Parameters:
      start - The starting index of the substring (inclusive).
      end - The ending index of the substring (exclusive).
      style - The integer style identifier to apply.

    • setStyle

      public void setStyle(String regexp, int style)
      Sets the font style for all substrings matching a given regular expression. If the font does not contain the specified style, the default style will be used.
      Parameters:
      regexp - The regular expression string to match against the text.
      style - The integer style identifier to apply.

    • setColor

      public void setColor(int start, int end, ColorRGBA color)
      Sets the color for a specific substring of the text.
      Parameters:
      start - The starting index of the substring (inclusive).
      end - The ending index of the substring (exclusive).
      color - The desired ColorRGBA to apply to the substring.

    • setColor

      public void setColor(String regexp, ColorRGBA color)
      Sets the color for all substrings matching a given regular expression.
      Parameters:
      regexp - The regular expression string to match against the text.
      color - The desired ColorRGBA to apply.

    • setTabPosition

      public void setTabPosition(float... tabs)
      Sets custom tab stop positions for the text. Tab characters (`\t`) will align to these specified positions.
      Parameters:
      tabs - An array of float values representing the horizontal tab stop positions.

    • setTabWidth

      public void setTabWidth(float width)
      Sets the default width for tabs that extend beyond the last defined tab position. This value is used if a tab character is encountered after all custom tab stops have been passed.
      Parameters:
      width - The default width for tabs in font units.

    • setEllipsisChar

      public void setEllipsisChar(char c)
      When LineWrapMode.NoWrap is used and the text exceeds the bounding box, this character will be appended to indicate truncation (e.g., '...').
      Parameters:
      c - The character to use as the ellipsis.

    • setLineWrapMode

      public void setLineWrapMode(LineWrapMode wrap)
      Sets the line wrapping mode for the text. This is only applicable when a text bounding box has been set using setBox(Rectangle).
      Parameters:
      wrap - The desired LineWrapMode:

    • updateLogicalState

      public void updateLogicalState(float tpf)
      Description copied from class: Spatial
      updateLogicalState calls the update() method for all controls attached to this Spatial.
      Overrides:
      updateLogicalState in class Node
      Parameters:
      tpf - Time per frame.
      See Also:

    • render

      public void render(RenderManager rm, ColorRGBA color)
      Renders the `BitmapText` spatial. This method iterates through each `BitmapTextPage`, sets its texture, and renders it using the provided `RenderManager`.
      Parameters:
      rm - The `RenderManager` responsible for drawing.
      color - The base color to apply during rendering. Note that colors set per-substring will override this for those parts.