Text.h File Reference

Text rendered with TrueType fonts. More...

#include <SDL3/SDL_gpu.h>
#include <ObjectivelyMVC/Font.h>
#include <ObjectivelyMVC/ImageAtlas.h>
#include <ObjectivelyMVC/View.h>

Go to the source code of this file.

Data Structures
struct	Text
	Text rendered with TrueType fonts. More...
struct	TextRun
	One quad of a rendered TrueType Text: a region of its texture, in texels, drawn in color, or, when icon is set, that icon drawn as a square of the line height within it. More...
struct	TextSpan
	One span of a laid-out string, in bytes of the layout string MVC_LayoutText returns: either the characters drawn in color, or a placeholder standing in for icon. More...

Enumerations
enum	TextTransform { TextTransformNone , TextTransformUppercase , TextTransformLowercase , TextTransformCapitalize }
	Case transforms a Text applies when drawing, leaving Text::text as set. More...

Functions
OBJECTIVELYMVC_EXPORT Class *	_Text (void)
OBJECTIVELYMVC_EXPORT bool	MVC_HasColorEscapes (const char *text)
OBJECTIVELYMVC_EXPORT size_t	MVC_IconEscapeLength (const char *chars, const ImageAtlas *icons, AtlasImage **image)
	Parses an icon escape at the start of chars: :name:, where name is one or more of [A-Za-z0-9_-] and under 64 bytes, and is registered in icons. An unregistered name is not an escape, so 12:30:45 stays literal unless someone registers an icon called 30.
OBJECTIVELYMVC_EXPORT char *	MVC_LayoutText (const Font *font, const char *text, SDL_Color color, const ImageAtlas *icons, TextSpan **spans, size_t *count)
	Resolves the escapes in text into the string to lay out and the spans to draw it as.
OBJECTIVELYMVC_EXPORT char *	MVC_StripColorEscapes (const char *text)
	Strips color escape sequences from the given text: ^0 through ^9 are removed, and ^^ collapses to ^.

Variables
OBJECTIVELYMVC_EXPORT SDL_Color	TextEscapeColors [10]
	Color palette for text escape sequences (^0 through ^9).
OBJECTIVELYMVC_EXPORT const EnumName	TextTransformNames []

Detailed Description

Text rendered with TrueType fonts.

Definition in file Text.h.

Enumeration Type Documentation

TextTransform

enum TextTransform

Case transforms a Text applies when drawing, leaving Text::text as set.

ASCII letters only; multi-byte UTF-8 sequences and color escapes pass through unchanged. Resolved :icon: escapes also pass through unchanged, so icon names keep their case.

Enumerator
TextTransformNone
TextTransformUppercase
TextTransformLowercase
TextTransformCapitalize

Definition at line 67 of file Text.h.

             {
  TextTransformNone,
  TextTransformUppercase,
  TextTransformLowercase,
  TextTransformCapitalize
} TextTransform;

Function Documentation

_Text()

OBJECTIVELYMVC_EXPORT Class * _Text

(

void

)

Definition at line 988 of file Text.c.

                   {
  static Class *clazz;
  static Once once;
 
  do_once(&once, {
    clazz = _initialize(&(const ClassDef) {
      .name = "Text",
      .superclass = _View(),
      .instanceSize = sizeof(Text),
      .interfaceSize = sizeof(TextInterface),
      .initialize = initialize,
    });
  });
 
  return clazz;
}

MVC_HasColorEscapes()

OBJECTIVELYMVC_EXPORT bool MVC_HasColorEscapes

(

const char *

text

)

Parameters

text	The text, or NULL.

Returns

True if text contains a color escape (^0 through ^9, or ^^).

Definition at line 65 of file Text.c.

                                           {
 
  for (const char *p = text ? strchr(text, '^') : NULL; p; p = strchr(p + 1, '^')) {
    if (colorEscapeLength(p)) {
      return true;
    }
  }
 
  return false;
}

MVC_IconEscapeLength()

OBJECTIVELYMVC_EXPORT size_t MVC_IconEscapeLength	(	const char *	chars,
		const ImageAtlas *	icons,
		AtlasImage **	image
	)

Parses an icon escape at the start of chars: :name:, where name is one or more of [A-Za-z0-9_-] and under 64 bytes, and is registered in icons. An unregistered name is not an escape, so 12:30:45 stays literal unless someone registers an icon called 30.

Parameters

chars	The text, positioned at a candidate :.
icons	The icon ImageAtlas, or NULL for none.
image	If not NULL, receives the icon, or NULL.

Returns

The byte length of the escape, or 0 if chars does not start with one.

Definition at line 104 of file Text.c.

                                                                                            {
 
  if (image) {
    *image = NULL;
  }
 
  if (chars == NULL || icons == NULL || chars[0] != ':') {
    return 0;
  }
 
  const char *q = chars + 1;
  while (SDL_isalnum((unsigned char) *q) || *q == '_' || *q == '-') {
    q++;
  }
 
  char name[64];
  const size_t len = q - chars - 1;
 
  if (*q != ':' || len == 0 || len >= sizeof(name)) {
    return 0;
  }
 
  memcpy(name, chars + 1, len);
  name[len] = '\0';
 
  AtlasImage *icon = $(icons, imageWithName, name);
  if (icon == NULL) {
    return 0;
  }
 
  if (image) {
    *image = icon;
  }
 
  return len + 2;
}

MVC_LayoutText()

OBJECTIVELYMVC_EXPORT char * MVC_LayoutText	(	const Font *	font,
		const char *	text,
		SDL_Color	color,
		const ImageAtlas *	icons,
		TextSpan **	spans,
		size_t *	count
	)

Resolves the escapes in text into the string to lay out and the spans to draw it as.

^N selects a color for what follows, ^^ becomes ^, and a registered :icon: becomes a run of placeholder characters at least a line height wide, for the icon to be drawn over. The placeholder is never a line-break opportunity, so an icon stays with its word. With no icons, and spans NULL, the result is that of MVC_StripColorEscapes.

Parameters

font	The Font the text will be laid out in.
text	The text.
color	The color in effect at the start of text.
icons	The icon ImageAtlas, or NULL for none.
spans	If not NULL, receives the spans, which the caller MUST free.
count	If not NULL, receives the number of spans; meaningful only with spans.

Returns

The layout string, which the caller MUST free.

Definition at line 220 of file Text.c.

                                                                                                                                    {
 
  assert(font);
  assert(text);
 
  LayoutBuffer layout = { 0 };
  append(&layout, "", 0);
 
  size_t n = 0;
  if (spans) {
    *spans = NULL;
  }
 
  size_t start = 0;
 
  for (const char *p = text; ; ) {
 
    const bool end = *p == '\0';
    const bool escape = !end && p[0] == '^' && p[1] >= '0' && p[1] <= '9';
 
    AtlasImage *icon = NULL;
    const size_t iconLength = (!end && *p == ':') ? MVC_IconEscapeLength(p, icons, &icon) : 0;
 
    if (end || escape || iconLength) {
      if (layout.length > start) {
        appendSpan(spans, &n, (TextSpan) { (int) start, (int) (layout.length - start), color, NULL });
      }
      if (end) {
        break;
      }
      if (escape) {
        color = TextEscapeColors[p[1] - '0'];
        p += 2;
      } else {
        const char *placeholder = iconPlaceholder(font);
        appendSpan(spans, &n, (TextSpan) { (int) layout.length, (int) strlen(placeholder), Colors.White, icon });
        append(&layout, placeholder, strlen(placeholder));
        p += iconLength;
      }
      start = layout.length;
    } else if (p[0] == '^' && p[1] == '^') {
      append(&layout, "^", 1);
      p += 2;
    } else {
      append(&layout, p, 1);
      p++;
    }
  }
 
  if (count) {
    *count = n;
  }
 
  return layout.chars;
}

MVC_StripColorEscapes()

OBJECTIVELYMVC_EXPORT char * MVC_StripColorEscapes

(

const char *

text

)

Strips color escape sequences from the given text: ^0 through ^9 are removed, and ^^ collapses to ^.

Parameters

text

The text.

Returns

A newly allocated copy of text without escape sequences. The caller must free it.

Definition at line 83 of file Text.c.

                                              {
 
  assert(text);
 
  char *stripped = malloc(strlen(text) + 1);
  size_t idx = 0;
 
  for (const char *p = text; *p; p++) {
    if (p[0] == '^' && p[1] >= '0' && p[1] <= '9') {
      p++;
    } else if (p[0] == '^' && p[1] == '^') {
      stripped[idx++] = *p++;
    } else {
      stripped[idx++] = *p;
    }
  }
 
  stripped[idx] = '\0';
  return stripped;
}

Variable Documentation

TextEscapeColors

OBJECTIVELYMVC_EXPORT SDL_Color TextEscapeColors[10]

Color palette for text escape sequences (^0 through ^9).

Escapes are always interpreted, on every Text: ^N selects TextEscapeColors[N] for the characters that follow, and ^^ renders a literal ^. Embedding applications MAY customize this array at runtime, before rendering.

Default mapping: ^0 Black, ^1 Red, ^2 Green, ^3 Yellow, ^4 Blue, ^5 Magenta, ^6 Cyan, ^7 White, ^8 Orange, ^9 Grey.

Definition at line 46 of file Text.h.

TextTransformNames

OBJECTIVELYMVC_EXPORT const EnumName TextTransformNames[]

Definition at line 74 of file Text.h.