1
0
Fork 0
mirror of https://github.com/Ellpeck/MLEM.git synced 2024-11-16 10:53:11 +01:00
MLEM/Docs/articles/text_formatting.md

64 lines
3.6 KiB
Markdown
Raw Normal View History

# Text Formatting
2020-05-21 01:08:36 +02:00
The **MLEM** package contains a simple text formatting system that supports coloring, bold and italic font modifiers, in-text icons and text animations.
Text formatting makes use of [generic fonts](font_extensions.md).
2020-05-21 01:08:36 +02:00
It should also be noted that [MLEM.Ui](https://github.com/Ellpeck/MLEM/wiki/MLEM.Ui)'s `Paragraph`s support text formatting out of the box.
*This documentation is about the new text formatting that was introduced in MLEM 3.3.1. You can see the documentation for the legacy text formatting system [here](text_formatting_legacy.md).*
2020-05-21 01:08:36 +02:00
## Formatting codes
To format your text, you can insert *formatting codes* into it. Almost all of these codes are single letters surrounded by `<>`, and some formatting codes can accept additional parameters after their letter representation.
2020-05-21 01:08:36 +02:00
By default, the following formatting options are available:
- Colors using `<c ColorName>`. All default MonoGame colors are supported, for example `<c CornflowerBlue>`. Reset using `</c>`.
- Bold and italic text using `<b>` and `<i>`, respectively. Reset using `</b>` and `</i>`.
- Drop shadows using `<s>`. Optional parameters for the shadow's color and positional offset are accepted: `<s #AARRGGBB 2.5>`. Reset using `</c>`.
- Underlined text using `<u>`. Reset using `</u>`.
- A wobbly sine wave animation using `<a wobbly>`. Optional parameters for the wobble's intensity and height are accepted: `<a wobbly 10 0.25>`. Reset using `</a>`.
## Getting your text ready
To get your text ready for rendering with formatting codes, it has to be tokenized. For that, you need to create a new text formatter first. Additionally, you need to have a [generic font](font_extensions.md) ready:
2020-05-21 01:08:36 +02:00
```cs
var font = new GenericSpriteFont(this.Content.Load<SpriteFont>("Fonts/ExampleFont"));
var formatter = new TextFormatter();
2020-05-21 01:08:36 +02:00
```
You can then tokenize your string like so:
2020-05-21 01:08:36 +02:00
```cs
var tokenizedString = formatter.Tokenize(font, "This is a <c Green>formatted</c> string!");
2020-05-21 01:08:36 +02:00
```
Additionally, if you want your tokenized string to be split based on a certain maximum width automatically, you can split it like so:
2020-05-21 01:08:36 +02:00
```cs
tokenizedString.Split(font, maxWidth, scale);
```
## Drawing the formatted text
To draw your tokenized text, all you have to do is call its `Draw` method like so:
2020-05-21 01:08:36 +02:00
```cs
tokenizedString.Draw(gameTime, spriteBatch, position, font, color, scale, depth);
2020-05-21 01:08:36 +02:00
```
Note that, if your tokenized text contains any animations, you have to updated the tokenized string every `Update` call like so:
2020-05-21 01:08:36 +02:00
```cs
tokenizedString.Update(gameTime);
```
## Adding custom codes
Adding custom formatting codes is easy! There are two things that a custom formatting code requires:
- A class that extends `Code` that does what your formatting code should do (we'll use `MyCustomCode` in this case)
- A regex that determines what strings your formatting code matches
- A formatting code constructor that creates a new instance of your code's class
You can then register your formatting code like this:
2020-05-21 01:08:36 +02:00
```cs
formatter.Codes.Add(new Regex("<matchme>"), (form, match, regex) => new MyCustomCode(match, regex));
2020-07-01 14:30:47 +02:00
```
## Macros
The text formatting system additionally supports macros: Regular expressions that cause the matched text to expand into a different string. Macros can be resolved recursively, meaning that you can have macros that resolve into other macros, and so on.
By default, the following macros are available:
- `~` expands into a non-breaking space, much like in LaTeX.
Adding custom macros is very similar to adding custom formatting codes:
```cs
formatter.Macros.Add(new Regex("matchme"), (form, match, regex) => "replacement string");
2020-05-21 01:08:36 +02:00
```