From ed96938a1cd79ba8199c607ae6caf5c10ceeb3c2 Mon Sep 17 00:00:00 2001 From: Ellpeck Date: Mon, 8 Nov 2021 02:50:53 +0100 Subject: [PATCH] updated documentation articles --- CHANGELOG.md | 2 +- Docs/articles/font_extensions.md | 11 ++-- Docs/articles/text_formatting.md | 14 +++-- Docs/articles/text_formatting_legacy.md | 76 ------------------------- Docs/articles/ui.md | 2 +- 5 files changed, 16 insertions(+), 89 deletions(-) delete mode 100644 Docs/articles/text_formatting_legacy.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b4635b..bde90ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ Additions - Added StaticSpriteBatch class Improvements +- Cache TokenizedString inner offsets for non-Left text alignments to improve performance - Exposed Camera's RoundPosition - Exposed the epsilon value used by Camera @@ -23,7 +24,6 @@ Additions - Added a multiline editing mode to TextField Improvements -- Cache TokenizedString inner offsets for non-Left text alignments to improve performance - Exposed the epsilon value used by Element calculations - Made Image ScaleToImage take ui scale into account - Added style properties for a lot of hardcoded default element styles diff --git a/Docs/articles/font_extensions.md b/Docs/articles/font_extensions.md index e1f4a99..21f510a 100644 --- a/Docs/articles/font_extensions.md +++ b/Docs/articles/font_extensions.md @@ -3,18 +3,17 @@ The **MLEM** base package features several additional font manipulation methods, including line splitting and text truncating. These abilities can be accessed through generic fonts. ## Generic fonts -MLEM features the `GenericFont` class along with a `GenericSpriteFont` implementation. This is used by the MLEM.Ui package, but it can also be used separately to have more control over font rendering. +MLEM features the `GenericFont` class along with a `GenericSpriteFont` implementation. This is used by the **MLEM.Ui** package, but it can also be used separately to have more control over font rendering. -The reason generic fonts exist is to provide the ability to use both MonoGame `SpriteFonts` and [MonoGame.Extended](http://www.monogameextended.net/) `BitmapFonts` for the additionally provided behavior. To access the latter, the **MLEM.Extended** package needs to be installed as well. +Additionally, the **MLEM.Extended** package provides the following generic fonts: +- `GenericBitmapFont`, which uses [MonoGame.Extended](http://www.monogameextended.net/)'s `SpriteFont` +- `GenericStashFont`, which uses [FontStashSharp](https://github.com/rds1983/FontStashSharp)'s fonts ### Creating a generic font -To create a generic font, simply create an instance of `GenericSpriteFont` or `GenericBitmapFont` when loading your game: +To create a generic font, simply create an instance of the desired generic font class when loading your game: ```cs // Using MonoGame SpriteFonts var spriteFont = new GenericSpriteFont(this.Content.Load("Fonts/ExampleFont")); - -// Using MonoGame.Extended BitmapFonts -var bitmapFont = new GenericBitmapFont(this.Content.Load("Fonts/ExampleBitmapFont")); ``` ## Line splitting diff --git a/Docs/articles/text_formatting.md b/Docs/articles/text_formatting.md index d5c879c..54995c7 100644 --- a/Docs/articles/text_formatting.md +++ b/Docs/articles/text_formatting.md @@ -6,16 +6,14 @@ Text formatting makes use of [generic fonts](font_extensions.md). It should also be noted that [MLEM.Ui](ui.md)'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).* - ## 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. By default, the following formatting options are available: - Colors using ``. All default MonoGame colors are supported, for example ``. Reset using ``. - Bold and italic text using `` and ``, respectively. Reset using `` and ``. -- Drop shadows using ``. Optional parameters for the shadow's color and positional offset are accepted: ``. Reset using ``. -- Underlined text using ``. Reset using ``. +- Drop shadows using ``. Optional parameters for the shadow's color and positional offset are accepted: ``. Reset using ``. +- Underlined and strikethrough text using `` and ``, respectively. Reset using `` and ``. - A wobbly sine wave animation using ``. Optional parameters for the wobble's intensity and height are accepted: ``. Reset using ``. ## Getting your text ready @@ -52,8 +50,14 @@ You can then register your formatting code like this: formatter.Codes.Add(new Regex(""), (form, match, regex) => new MyCustomCode(match, regex)); ``` +To add an in-text image formatting code, you can use the `ImageCodeExtensions.AddImage` extension. All you have to do is supply the texture region and a name: +```cs +formatter.AddImage("ImageName", new TextureRegion(texture, 0, 0, 8, 8)); +``` +After doing so, the image can be displayed using the code ``. + ## 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. +The text formatting system additionally supports macros: Regular expressions that cause the matched text to expand into a different string. Macros are 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. diff --git a/Docs/articles/text_formatting_legacy.md b/Docs/articles/text_formatting_legacy.md deleted file mode 100644 index b1a578d..0000000 --- a/Docs/articles/text_formatting_legacy.md +++ /dev/null @@ -1,76 +0,0 @@ -# Legacy Text Formatting - -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). - -It should also be noted that [MLEM.Ui](ui.md)'s `Paragraph`s support text formatting out of the box. - -## Formatting codes -To format your text, you can insert *formatting codes* into it. These codes are surrounded by `[]` by default, however these delimiters can be changed like so: -```cs -TextFormatting.SetFormatIndicators('<', '>'); -``` - -By default, the following formatting options are available: -- All default MonoGame `Color` values, for example `[CornflowerBlue]`, `[Red]` etc. -- `[Bold]` and `[Italic]` to switch to a bold or italic font (and `[Regular]` to switch back) -- `[Shadow]` to add a drop shadow to the text -- `[Wobbly]` for a sine wave text animation -- `[Typing]` for a typewriter-style text animation -- `[Unanimated]` to reset back to the default animation - -## Getting your text ready -To actually display the text with formatting, you first need to gather the formatting data from the text. For performance reasons, this is best done when the text changes, and not every render frame. - -To gather formatting data, you will need a [generic font](font_extensions.md). With it, you can gather the data in the form of a `FormattingCodeCollection` like so: -```cs -var font = new GenericSpriteFont(this.Content.Load("Fonts/ExampleFont")); -var text = "This is the [Blue]text[White] that should be [Wobbly]formatted[Unanimated]."; -var data = text.GetFormattingCodes(font); -``` - -Additionally, you will need an *unformatted* version of the string you want to display. There are two reasons for this: -- Removing formatting data from the string each frame is unnecessarily expensive -- You can use generic fonts' `SplitString` method to split the text you want to display into multiple lines without the text's lengths being tainted by the formatting codes within the string. - -You can remove a string's formatting data like so: -```cs -var unformatted = text.RemoveFormatting(font); -``` - -## Drawing the formatted text -Now that you have your font (`font`), the formatting data (`data`) and the unformatted string (`unformatted`), you can draw it like so: -```cs -font.DrawFormattedString(this.SpriteBatch, new Vector2(10, 10), unformatted, data, Color.White, scale: 1); -``` - -Additionally, the `DrawFormattedString` method accepts several optional parameters, including the font to be used for bold and italic text and more. - -### Time into animation -If you want to display animated text, you need to pass a `TimeSpan` into `DrawFormattedString` that determines the amount of time that has passed throughout the animation. You can do this easily by passing the `GameTime`'s `TotalGameTime` span: -```cs -font.DrawFormattedString(this.SpriteBatch, new Vector2(10, 10), unformatted, data, Color.White, scale: 1, - timeIntoAnimation: gameTime.TotalGameTime); -``` - -### Formatting settings -The `FormatSettings` class contains additional information for text formatting, like the speed of predefined animations and the color and offset of the drop shadow. To change these settings, you can simply pass an instance of `FormatSettings` to `DrawFormattedString`: -```cs -var settings = new FormatSettings { - DropShadowColor = Color.Pink, - WobbleHeightModifier = 1 -}; - -font.DrawFormattedString(this.SpriteBatch, new Vector2(10, 10), unformatted, data, Color.White, scale: 1, - formatSettings: settings); -``` - -## Adding custom codes -To add custom formatting codes (especially icons), you simple have to add to the `FormattingCodes` dictionary. The key is the name of the formatting code that goes between the delimiters (`[]`), and the value is an instance of `FormattingCode`: -```cs -// Creating an icon -TextFormatting.FormattingCodes["ExampleIcon"] = new FormattingCode(new TextureRegion(exampleTexture)); -// Creating a color -TextFormatting.FormattingCodes["ExampleColor"] = new FormattingCode(new Color(10, 20, 30)); -``` \ No newline at end of file diff --git a/Docs/articles/ui.md b/Docs/articles/ui.md index 74dbc1c..296cffe 100644 --- a/Docs/articles/ui.md +++ b/Docs/articles/ui.md @@ -62,7 +62,7 @@ var style = new UntexturedStyle(this.SpriteBatch) { ButtonTexture = new NinePatch(this.Content.Load("Textures/ExampleTexture"), padding: 1) }; ``` -Note that MLEM.Ui is also compatible with [MonoGame.Extended](http://www.monogameextended.net/)'s Bitmap Fonts by installing MLEM.Extended and using `GenericBitmapFont` instead. +Note that MLEM.Ui is also compatible with [MonoGame.Extended](http://www.monogameextended.net/)'s Bitmap Fonts by installing **MLEM.Extended** and using `GenericBitmapFont` instead. ### Scaling To change the scaling of your ui, you can use the `UiSystem`'s `Scale` property. Additionally, you can enable `AutoScaleWithScreen` to cause the entire ui to scale automatically when resizing the game window.