updated documentation for 3.3.2 release

Docs/articles/font_extensions.md

@@ -1,11 +1,13 @@
+# Font Extensions
+
 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
+## 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.
 
 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.
 
-## Creating a generic font
+### Creating a generic font
 To create a generic font, simply create an instance of `GenericSpriteFont` or `GenericBitmapFont` when loading your game:
 ```cs
 // Using MonoGame SpriteFonts
@@ -15,14 +17,14 @@ var spriteFont = new GenericSpriteFont(this.Content.Load<SpriteFont>("Fonts/Exam
 var bitmapFont = new GenericBitmapFont(this.Content.Load<BitmapFont>("Fonts/ExampleBitmapFont"));
 ```
 
-# Line splitting
+## Line splitting
 Using generic fonts, a long line of text can be split into multiple lines based on a maximum width in pixels. The split text that is returned is delimited by `\n` (newline characters).
 ```cs
 var split = spriteFont.SplitString("This is a really long line of text [...]", width: 100, scale: 1);
 spriteFont.DrawString(this.SpriteBatch, split, new Vector2(10, 10), Color.White);
 ```
 
-# Truncating
+## Truncating
 Using generic fonts, a long line of text can also be truncated to fit a certain width in pixels. The remaining text that doesn't fit will simply be chopped off of the end (or start) of the string.
 ```cs
 // Truncate from the front

Docs/articles/friends.md

@@ -1,3 +1,5 @@
+# Friends of MLEM
+
 There are several other NuGet packages that work well in combination with MonoGame and MLEM. Here are some of them:
 - [Contentless](https://github.com/Ellpeck/Contentless), a tool by Ellpeck that removes the need to add assets to the MonoGame Content Pipeline manually
 - [Coroutine](https://github.com/Ellpeck/Coroutine), a package by Ellpeck that implements Unity-style coroutines for any project

Docs/articles/input.md

@@ -1,8 +1,10 @@
+# Input Handler
+
 The **MLEM** base package features an extended `InputHandler` class that allows for finer control over inputs, like the ability to query a new *pressed* state as well as a repeat events implementation for both keyboard and gamepad input.
 
 Rather than using an event-based structure, the MLEM input handler relies on the game's `Update` frames: To query input through the input handler, you have to query it every Update frame, and input information will only be available for a single update frame in most situations.
 
-# Setting it up
+## Setting it up
 To set it up, all you have to do is create a new instance. The constructor optionally accepts parameters to enable or disable certain kinds of input.
 ```cs
 this.InputHandler = new InputHandler();
@@ -12,7 +14,7 @@ Additionally, you will have to call the input handler's `Update` method each upd
 this.InputHandler.Update();
 ```
 
-# Querying pressed keys
+## Querying pressed keys
 A *pressed* key is a key that wasn't down the last update but is held down the current update. This behavior can be useful for things like ui buttons, where holding down the mouse button shouldn't constantly keep triggering the button.
 
 You can query if any key, mouse button or gamepad button is pressed as follows:
@@ -26,12 +28,12 @@ var gamepad = this.InputHandler.IsPressed(Buttons.A);
 var gamepad2 = this.InputHandler.IsPressed(Buttons.A, 2);
 ```
 
-## Repeat events
+### Repeat events
 Keyboard and gamepad repeat events can be enabled or disabled through the `HandleKeyboardRepeats` and `HandleGamepadRepeats` properties in the input handler. Additionally, you can configure the time that it takes until the first repeat is triggered through the `KeyRepeatDelay` property, and you can configure the delay between repeat events through the `KeyRepeatRate` property.
 
 When enabled, repeat events for *pressing* are automatically triggered. This means that calling `IsPressed` every update call would return `true` for a control that is being held down every `KeyRepeatRate` seconds after `KeyRepeatDelay` seconds have passed once.
 
-# Gesture handling
+## Gesture handling
 MonoGame's default touch handling can be a bit wonky to deal with, so the input handler also provides a much better user experience for touch gesture input.
 
 To enable touch input, the gestures you want to use first have to be enabled:

Docs/articles/raw_content.md

@@ -1,13 +1,15 @@
+# Raw Content Manager
+
 Sometimes, there's a good reason for wanting to load game assets directly rather than using the MonoGame Content Pipeline, which packs files into a binary `xnb` format. Those reasons include, for example, making your game easily moddable or allowing for texture packs.
 
 The **MLEM** package contains a solution for this: `RawContentManager`.
 
-# What it does
+## What it does
 A raw content manager works very similarly to a regular `ContentManager`: You can load different types of assets through the `Load<T>` method, and they will automatically be managed and disposed when the game closes.
 
 However, the `RawContentManager` loads assets in their usual file type, rather than `xnb`, meaning that they don't have to be compiled using the Content Pipeline first. 
 
-# How to use it
+## How to use it
 To create a new raw content manager, simply call its constructor in your `LoadContent` method. Optionally, you can add it as a game component, which will automatically dispose it when the game closes.
 ```cs
 protected override void LoadContent() {
@@ -23,7 +25,7 @@ Then, you can simply load an asset in your `Content` directory like you would wi
 this.testTexture = this.rawContent.Load<Texture2D>("Textures/Test");
 ```
 
-# Adding more content types
+## Adding more content types
 By default, the raw content manager supports the following types, as long as their files are appended with one of the supported file extensions:
 - `Texture2D` (png, bmp, gif, jpg, tif, dds)
 - `SoundEffect` (ogg, wav, mp3)

Docs/articles/sprite_animations.md

@@ -1,6 +1,8 @@
+# Sprite Animations
+
 The **MLEM** package contains a very simple sprite animation system that features different-length frames as well as animation grouping.
 
-# Using animations
+## Using animations
 You can create an animation like so:
 ```cs
 var texture = this.Content.Load<Texture2D>("Textures/TestSprite");
@@ -27,7 +29,7 @@ You can draw the animation's current frame as follows:
 this.SpriteBatch.Draw(anim1.CurrentRegion, new Vector2(10, 10), Color.White);
 ```
 
-# Using animation groups
+## Using animation groups
 Animation groups consist of multiple animations. Each animation in a group has a condition that determines if it should currently be playing.
 
 You can create an animation group and add animations to it like so:

Docs/articles/startup.md

@@ -1,3 +1,5 @@
+# MLEM.Startup
+
 **MLEM.Startup** is a simple package that contains a `MlemGame` class which extends MonoGame's `Game`. This class contains additional properties that most games created with MonoGame and MLEM will have:
 - An [InputHandler](https://github.com/Ellpeck/MLEM/wiki/Input-Handler)
 - A `SpriteBatch` and `GraphicsDeviceManager`

Docs/articles/text_formatting.md

@@ -1,74 +1,53 @@
+# 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](https://github.com/Ellpeck/MLEM/wiki/Font-Extensions).
+Text formatting makes use of [generic fonts](font_extensions.md).
 
 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.
 
-# Formatting codes
+*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).*
-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
+## Formatting codes
-TextFormatting.SetFormatIndicators('<', '>');
+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:
-- All default MonoGame `Color` values, for example `[CornflowerBlue]`, `[Red]` etc.
+- Colors using `<c ColorName>`. All default MonoGame colors are supported, for example `<c CornflowerBlue>`. Reset using `</c>`.
-- `[Bold]` and `[Italic]` to switch to a bold or italic font (and `[Regular]` to switch back)
+- Bold and italic text using `<b>` and `<i>`, respectively. Reset using `</b>` and `</i>`.
-- `[Shadow]` to add a drop shadow to the text
+- Drop shadows using `<s>`. Optional parameters for the shadow's color and positional offset are accepted: `<s #AARRGGBB 2.5>`. Reset using `</c>`.
-- `[Wobbly]` for a sine wave text animation
+- Underlined text using `<u>`. Reset using `</u>`.
-- `[Typing]` for a typewriter-style text animation
+- 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>`.
-- `[Unanimated]` to reset back to the default animation
 
-# Getting your text ready
+## 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 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:
-
-To gather formatting data, you will need a [generic font](https://github.com/Ellpeck/MLEM/wiki/Font-Extensions). With it, you can gather the data in the form of a `FormattingCodeCollection` like so:
 ```cs
 var font = new GenericSpriteFont(this.Content.Load<SpriteFont>("Fonts/ExampleFont"));
-var text = "This is the [Blue]text[White] that should be [Wobbly]formatted[Unanimated].";
+var formatter = new TextFormatter();
-var data = text.GetFormattingCodes(font);
 ```
-
+You can then tokenize your string like so:
-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);
+var tokenizedString = formatter.Tokenize(font, "This is a <c Green>formatted</c> string!");
 ```
-
+Additionally, if you want your tokenized string to be split based on a certain maximum width automatically, you can split it like so:
-# 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);
+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:
+```cs
+tokenizedString.Draw(gameTime, spriteBatch, position, font, color, scale, depth); 
 ```
-
+Note that, if your tokenized text contains any animations, you have to updated the tokenized string every `Update` call like so:
-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,
+tokenizedString.Update(gameTime);
-    timeIntoAnimation: gameTime.TotalGameTime);
+``` 
-```
+## 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
 
-## Formatting settings
+You can then register your formatting code like this:
-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 {
+formatter.Codes.Add(new Regex("<matchme>"), (form, match, regex) => new MyCustomCode(match, regex));
-    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));
 ```

Docs/articles/text_formatting_legacy.md

@@ -0,0 +1,76 @@
+# 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](https://github.com/Ellpeck/MLEM/wiki/MLEM.Ui)'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](https://github.com/Ellpeck/MLEM/wiki/Font-Extensions). With it, you can gather the data in the form of a `FormattingCodeCollection` like so:
+```cs
+var font = new GenericSpriteFont(this.Content.Load<SpriteFont>("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));
+```

Docs/articles/tiled_extensions.md

@@ -1,6 +1,8 @@
+# Tiled Extensions
+
 If you're using [MonoGame.Extended](https://github.com/craftworkgames/MonoGame.Extended)'s [Tiled](https://www.mapeditor.org/) map editor support, you can use the **MLEM.Extended** package alongside that to enhance your tilemap experience.
 
-# Extensions
+## Extensions
 There are several extensions to tiled maps, tilesets and tiles, including, but not limited to:
 - The ability to get a tileset tile from a tile easily
 - The ability to get tile and tile map properties easily
@@ -8,7 +10,7 @@ There are several extensions to tiled maps, tilesets and tiles, including, but n
 
 All of these extension methods can be found in the [TiledExtensions](https://github.com/Ellpeck/MLEM/blob/master/MLEM.Extended/Tiled/TiledExtensions.cs) class.
 
-# Tiled map collisions
+## Tiled map collisions
 MLEM.Extended includes a very easy way to set up collisions within your tiled maps through the use of [tile collisions](https://doc.mapeditor.org/en/stable/manual/editing-tilesets/#tile-collision-editor).
 
 To get this set up, you simply have to add bounding rectangles to your tilesets within the Tiled editor. Then, you can query collisions like so:
@@ -23,7 +25,7 @@ var tiles = collisions.GetCollidingTiles(new RectangleF(2, 2, 3.5F, 3.5F));
 var colliding = collisions.IsColliding(new RectangleF(4, 4, 1, 1));
 ```
 
-## Collision coordinate system
+### Collision coordinate system
 The coordinate system of these tiled collisions functions based on *percentages* rather than absolute pixel coordinates. The collision system sees each tile as being *one unit by one unit* big.
 
 This means that, to check if the tile at tile coordinate `6, 10` contains any collisions, the following rectangle has to be used:

Docs/articles/ui.md

@@ -1,8 +1,10 @@
+# MLEM.Ui
+
 **MLEM.Ui** is a Ui framework for MonoGame that features elements with automatic positioning and sizing. It contains various ready-made element types like buttons, paragraphs, text fields and more, along with the ability to easily create custom controls. It supports **mouse**, **keyboard**, **gamepad** and **touch** input with little to no additional setup work required.
 
 To see some of what MLEM.Ui can do, you can check out [the demo](https://github.com/Ellpeck/MLEM/blob/master/Demos/UiDemo.cs) as well.
 
-# Setting it up
+## Setting it up
 To get set up with MLEM.Ui, there are only a few things that need to be done in your Game class:
 ```cs
 public UiSystem UiSystem;
@@ -31,7 +33,7 @@ protected override void Draw(GameTime gameTime) {
 }
 ```
 
-## Text Input
+### Text Input
 Text input is a bit weird in MonoGame. On Desktop devices, you have the `Window.TextInput` event that gets called automatically with the correct characters for the keys that you're pressing, even for non-American keyboards. However, this function doesn't just *not work* on other devices, it doesn't exist there at all. So, to make MLEM.Ui compatible with all devices without publishing a separate version for each MonoGame system, you have to set up the text input wrapper yourself, based on the system you're using MLEM.Ui with. This has to be done *before* initializing your `UiSystem`.
 
 DesktopGL:
@@ -51,7 +53,7 @@ If you're not using text input, you can just set the wrapper to a stub one like
 TextInputWrapper.Current = new TextInputWrapper.None();
 ```
 
-# Setting the style
+## Setting the style
 By default, MLEM.Ui's controls look pretty bland, since it doesn't ship with any fonts or textures for any of its controls. To change the style of your ui, simply expand your `new UntexturedStyle(this.SpriteBatch)` call to include fonts and textures of your choosing, for example:
 ```cs
 var style = new UntexturedStyle(this.SpriteBatch) {
@@ -61,10 +63,10 @@ var style = new UntexturedStyle(this.SpriteBatch) {
 ```
 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
+### 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.
 
-# Adding elements
+## Adding elements
 To add elements to your ui, you first have to add a **root element**. A root element can be any type of element, but to add it to the ui system, you have to give it a name:
 ```cs
 var panel = new Panel(Anchor.Center, size: new Vector2(100, 100), positionOffset: Vector2.Zero);
@@ -85,7 +87,7 @@ box.AddChild(new Button(Anchor.AutoCenter, new Vector2(0.5F, 20), "Okay") {
 this.UiSystem.Add("InfoBox", box);
 ```
 
-## About sizing
+### About sizing
 Note that, when setting the width and height of any element, there are some things to note:
 - Each element has a `SetWidthBasedOnChildren` and a `SetHeightBasedOnChildren` property, which allow them to change their size automatically based on their content
 - When specifying a width or height *lower than or equal to 1*, it is seen as a percentage based on the parent's size instead. For example, a paragraph with a width of `0.5F` inside of a panel width a width of `200` will be `100` units wide.