updated documentation articles

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,13 +24,13 @@ 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
 - Allow style properties to set style values with a higher priority, which allows elements to style their default children
 - Allow changing the entire ui style for a single element
 - Skip unnecessary area updates for elements with dirty parents
+- Calculate panel scroll bar height based on content height
 
 Fixes
 - Fixed VerticalSpace height parameter being an integer

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<SpriteFont>("Fonts/ExampleFont"));
-
-// Using MonoGame.Extended BitmapFonts
-var bitmapFont = new GenericBitmapFont(this.Content.Load<BitmapFont>("Fonts/ExampleBitmapFont"));
 ```
 
 ## Line splitting

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 `<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>`.
+- Drop shadows using `<s>`. Optional parameters for the shadow's color and positional offset are accepted: `<s #AARRGGBB 2.5>`. Reset using `</s>`.
+- Underlined and strikethrough text using `<u>` and `<st>`, respectively. Reset using `</u>` and `</st>`.
 - 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
@@ -52,8 +50,14 @@ You can then register your formatting code like this:
 formatter.Codes.Add(new Regex("<matchme>"), (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 `<i ImageName>`.
+
 ## 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.

Docs/articles/text_formatting_legacy.md

@@ -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<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/ui.md

@@ -62,7 +62,7 @@ var style = new UntexturedStyle(this.SpriteBatch) {
     ButtonTexture = new NinePatch(this.Content.Load<Texture2D>("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.

MLEM.Ui/Elements/Panel.cs

@@ -39,7 +39,8 @@ namespace MLEM.Ui.Elements {
         /// </summary>
         public StyleProp<float> StepPerScroll;
         /// <summary>
-        /// The size that the <see cref="ScrollBar"/>'s scroller should have, in pixels
+        /// The size that the <see cref="ScrollBar"/>'s scroller should have, in pixels.
+        /// The scroller size's height specified here is the minimum height, otherwise, it is automatically calculated based on panel content.
         /// </summary>
         public StyleProp<Vector2> ScrollerSize;
 
@@ -220,12 +221,22 @@ namespace MLEM.Ui.Elements {
             // if there is only one child, then we have just the scroll bar
             if (this.Children.Count == 1)
                 return;
+
             // the "real" first child is the scroll bar, which we want to ignore
             var firstChild = this.Children.First(c => c != this.ScrollBar);
             var lowestChild = this.GetLowestChild(c => c != this.ScrollBar && !c.IsHidden);
-            // the max value of the scrollbar is the amount of non-scaled pixels taken up by overflowing components
             var childrenHeight = lowestChild.Area.Bottom - firstChild.Area.Top;
-            this.ScrollBar.MaxValue = (childrenHeight - this.Area.Height) / this.Scale + this.ChildPadding.Value.Height;
+
+            // the max value of the scrollbar is the amount of non-scaled pixels taken up by overflowing components
+            var scrollBarMax = (childrenHeight - this.ChildPaddedArea.Height) / this.Scale;
+            if (!this.ScrollBar.MaxValue.Equals(scrollBarMax, Epsilon)) {
+                this.ScrollBar.MaxValue = scrollBarMax;
+                this.relevantChildrenDirty = true;
+            }
+
+            // the scroller height has the same relation to the scroll bar height as the visible area has to the total height of the panel's content
+            var scrollerHeight = Math.Min(this.ChildPaddedArea.Height / childrenHeight / this.Scale, 1) * this.ScrollBar.Area.Height;
+            this.ScrollBar.ScrollerSize = new Vector2(this.ScrollerSize.Value.X, Math.Max(this.ScrollerSize.Value.Y, scrollerHeight));
 
             // update the render target
             var targetArea = (Rectangle) this.GetRenderTargetArea();
@@ -253,7 +264,6 @@ namespace MLEM.Ui.Elements {
                 return;
             this.ScrollBar.StepPerScroll = this.StepPerScroll;
             this.ScrollBar.Size = new Vector2(this.ScrollerSize.Value.X, 1);
-            this.ScrollBar.ScrollerSize = this.ScrollerSize;
             this.ScrollBar.PositionOffset = new Vector2(-this.ScrollerSize.Value.X - 1, 0);
         }