Skip to content

Text

Jump to bottom
Philip Howard edited this page Dec 28, 2020 · 5 revisions

Text

The 32blit engine supplies several functions for drawing text to the screen - or another surface - in your font of choice.

Drawing Text

There are two methods for drawing text, one that uses a Rect to define a bounding box, inside which text is wrapped:

void text(std::string_view message, const Font &font, const Rect &r, bool variable = true, TextAlign align = TextAlign::top_left);

And one that uses a Point defining the origin of the text, which is the top-left corner by default:

void text(std::string_view message, const Font &font, const Point &p, bool variable = true, TextAlign align = TextAlign::top_left);

Fonts

Built-in Fonts

32blit provides three built-in fonts to get you started.

  1. Minimal Font - minimal_font
  2. Outline Font - outline_font
  3. Fat Font - fat_font

Custom Fonts

Custom fonts can be added to your game using the 32blit asset pipeline. ttf fonts are recognised and converted automatically. gif and png images are also supported, and should define individual glpyhs in a regular grid.

Rect/Point Position

Using a Rect will specify a container for the text, explicitly defining the top, left, bottom and right edges against which it will be aligned.

A Point defines the origin of the text, and text will be aligned against this point- right-aligned text will draw on the left of the point, left-aligned text will draw on the right of the point and so on.

Fixed/Variable Width

Fixed width text ensures that every character is the same width, so the length of the rendered text is predictable. This might be used where a space for n digits (such as a two digit lives count) is reserved in the interface.

Variable width is great for readability where text does not need to fit in a specific bounding box and might wrap and scroll.

Alignment

The 5th argument to screen.text allows text alignment to be set using a 4-bit flag.

screen.text(text, minimal_font, text_rect, variable_width, TextAlign::center_center);

The following alignment options are available:

  • Left - TextAlign::left
  • Center (Horizontal) - TextAlign::center_h
  • Right - TextAlign::right
  • Top - TextAlign::top
  • Center (Vertical) - TextAlign::center_v
  • Bottom - TextAlign::bottom

There are also shorthands for valid alignment combinations:

  • Top Left - TextAlign::top_left
  • Center Left - TextAlign::center_left
  • Bottom Left - TextAlign::bottom_left
  • Top Center - TextAlign::top_center
  • Center - TextAlign::center_center
  • Bottom Center - TextAlign::bottom_center
  • Top Right - TextAlign::top_right
  • Center Right - TextAlign::center_right
  • Bottom Right - TextAlign::bottom_right

Masking/Clipping

The display clipping rectangle affects text like any other drawing operation.

Set a rectangle to screen.clip and text will not be drawn outside of this region.

Get Text Size

Knowing the width/height of text is useful for positioning. It can be obtained with measure_text which returns a Size object with w and h properties.

Size measure_text(std::string_view message, const Font &font, bool variable = true);

Wrap Text

draw_text will not wrap text for if it reaches the bounds of its containing Rect. Text must be wrapped explicitly before being drawn. This is accomplished either explitly using \n or using wrap_text, which accepts broadly the same arguments as draw_text:

std::string wrap_text(std::string_view message, int32_t width, const Font &font, bool variable = true, bool words = true);

Text is wrapped to width, breaking at letter boundaries and potentially breaking works. The newline character - \n - should be used to force linebreaks where breaking words is undesired.

Clone this wiki locally