[email protected]

## [2.2.0-preview.3] - 2022-03-07
### Changes
- Fixed a potential IndexOutOfRangeException when trying to select any portions of text in an Input Field whose child text component is using Overflow mode Truncate or Ellipsis where due to RectTransform width and / or height restrictions have results in the text being fully truncated. Case #1361032
- Fixed incorrect character sequencing in the Input Field when using Japanese IME in UWP builds. Case #1374755
- Fixed several potential IndexOutOfRangeException in the Input Field when text is fully truncated when using Text Overflow mode Ellipsis or Truncate.
- Fixed Input Field incorrect caretPosition and / or stringPosition properties when updating these via scripting. Case #1334622
- Fixed incorrect event handling on UWP and Hololens 2. Case #1357718 and Case #1351006
- Fixed Input Field OnSelect event potentially firing twice on some mobile devices including Microsoft Surfaces.
- Fixed Input Field incorrect caret insertion position when text contains a Carriage Return <CR> at the end of a line. Case #1362068
- Added support for <CR> markup tag.
- Added value range check for the text component margins located in the text component extra settings. Case #1365554
- Added new overload to the TMP_FontAsset.CreateFontAsset() to enable creating font asset instances using a file path.
- Added new TMP_ResourceManager.RemoveFontAsset() function to remove a font asset from the TMP Resource Manager. This new function would typically be used prior to unloading bundles and / or resources.
- Warnings about potentially missing character 0x5F used to display underline or strikethrough will only be displayed when using those features when Display Warning is enabled in the TMP Settings.
- Fixed incorrect handling of '-' at the end of a line when using Text Overflow Page mode. Case #1382173
- Fixed incorrect line breaking when a hyphen '-' is preceded by a space. Case #1391990
- When using Text Wrapping Mode - Preserve White Space or Preserve White Space No Wrap, the <ZWSP> character will now contribute to the preferred height when it is the first and only character on a new line.
- Added ClearFontAssetGlyphCache() function to the TMP_ResourcesManager to enable clearing the font asset fallback glyph cache.
- Added new <ZWJ> markup tag.
- Added ability to define a list of fallback text assets in the TMP Settings to be used for Emojis.
- Added new property "emojiFallbackSupport" to text components which is also exposed in the extra settings section of the text component inspector. When enabled, this will prioritize searching the Emoji Fallback Text Assets before the primary font asset for characters defined as Emoji in Unicode 14.0. See [forum post](https://forum.unity.com/threads/fallback-to-emojis-before-fonts.1186174/) for details.
- Fixed duplicated character when using custom validator in conjunction with soft keyboard. Case #1387772
- The <noparse> markup tag will now also affect inline markup tags like <br>, <shy>, etc.
- Fixed newly created StyleSheets having two Normal styles.
- Added new Double Pass SDF shader and example scene to the TMP Examples & Extras to showcase this new shader.
- Added new context menu option to manually "clear dynamic data" of a dynamic font asset. This performs the same clearing of data as the "Clear Dynamic Data on Build" option when manually triggered.
- Added new <a href="url"> markup tag which can be used as follows: "See <a href="http://url...">this link</a> for details.". This new markup tag is similar to the <link> tag but does not use an ID.
- Added new "A" style to the Default Style Sheet referenced in the TMP Settings. This "A" style defines the styling of the new <a> markup tag.
- The TMP_Text.parseCtrlCharacters property which controls the interpretation and parsing of escape characters in the text component's Text Input box in the inspector, will now apply to all methods of setting the text on the component. Case #1400008
- Fixed potential Null Reference Exception when editing the name of a sprite character. Case #1396591
- Fixed issue where TMP_FontAsset.HasCharacters would return false when called prior to font asset initialization. Case #1394817
- Minor TMP_InputField UI improvement where "Hide Mobile Input" property will be disabled when "Hide Soft Keyboard" property is disabled. Case #1388243

CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 These are the release notes for the TextMesh Pro UPM package which was first introduced with Unity 2018.1. Please see the following link for the Release Notes for prior versions of TextMesh Pro. http://digitalnativestudios.com/forum/index.php?topic=1363.0
 
+## [2.2.0-preview.3] - 2022-03-07
+### Changes
+- Fixed a potential IndexOutOfRangeException when trying to select any portions of text in an Input Field whose child text component is using Overflow mode Truncate or Ellipsis where due to RectTransform width and / or height restrictions have results in the text being fully truncated. Case #1361032 
+- Fixed incorrect character sequencing in the Input Field when using Japanese IME in UWP builds. Case #1374755
+- Fixed several potential IndexOutOfRangeException in the Input Field when text is fully truncated when using Text Overflow mode Ellipsis or Truncate.
+- Fixed Input Field incorrect caretPosition and / or stringPosition properties when updating these via scripting. Case #1334622
+- Fixed incorrect event handling on UWP and Hololens 2. Case #1357718 and Case #1351006
+- Fixed Input Field OnSelect event potentially firing twice on some mobile devices including Microsoft Surfaces.
+- Fixed Input Field incorrect caret insertion position when text contains a Carriage Return <CR> at the end of a line. Case #1362068
+- Added support for <CR> markup tag.
+- Added value range check for the text component margins located in the text component extra settings. Case #1365554
+- Added new overload to the TMP_FontAsset.CreateFontAsset() to enable creating font asset instances using a file path.
+- Added new TMP_ResourceManager.RemoveFontAsset() function to remove a font asset from the TMP Resource Manager. This new function would typically be used prior to unloading bundles and / or resources.
+- Warnings about potentially missing character 0x5F used to display underline or strikethrough will only be displayed when using those features when Display Warning is enabled in the TMP Settings.
+- Fixed incorrect handling of '-' at the end of a line when using Text Overflow Page mode. Case #1382173
+- Fixed incorrect line breaking when a hyphen '-' is preceded by a space. Case #1391990
+- When using Text Wrapping Mode - Preserve White Space or Preserve White Space No Wrap, the <ZWSP> character will now contribute to the preferred height when it is the first and only character on a new line.
+- Added ClearFontAssetGlyphCache() function to the TMP_ResourcesManager to enable clearing the font asset fallback glyph cache.
+- Added new <ZWJ> markup tag.
+- Added ability to define a list of fallback text assets in the TMP Settings to be used for Emojis.
+- Added new property "emojiFallbackSupport" to text components which is also exposed in the extra settings section of the text component inspector. When enabled, this will prioritize searching the Emoji Fallback Text Assets before the primary font asset for characters defined as Emoji in Unicode 14.0. See [forum post](https://forum.unity.com/threads/fallback-to-emojis-before-fonts.1186174/) for details.
+- Fixed duplicated character when using custom validator in conjunction with soft keyboard. Case #1387772
+- The <noparse> markup tag will now also affect inline markup tags like <br>, <shy>, etc.
+- Fixed newly created StyleSheets having two Normal styles.
+- Added new Double Pass SDF shader and example scene to the TMP Examples & Extras to showcase this new shader.
+- Added new context menu option to manually "clear dynamic data" of a dynamic font asset. This performs the same clearing of data as the "Clear Dynamic Data on Build" option when manually triggered.
+- Added new <a href="url"> markup tag which can be used as follows: "See <a href="http://url...">this link</a> for details.". This new markup tag is similar to the <link> tag but does not use an ID.
+- Added new "A" style to the Default Style Sheet referenced in the TMP Settings. This "A" style defines the styling of the new <a> markup tag.
+- The TMP_Text.parseCtrlCharacters property which controls the interpretation and parsing of escape characters in the text component's Text Input box in the inspector, will now apply to all methods of setting the text on the component. Case #1400008
+- Fixed potential Null Reference Exception when editing the name of a sprite character. Case #1396591
+- Fixed issue where TMP_FontAsset.HasCharacters would return false when called prior to font asset initialization. Case #1394817
+- Minor TMP_InputField UI improvement where "Hide Mobile Input" property will be disabled when "Hide Soft Keyboard" property is disabled. Case #1388243
+
 ## [2.2.0-preview.2] - 2021-10-31
 ### Changes
 - Fixed incorrect character spacing when using the <scale> tag. See [forum post](https://forum.unity.com/threads/inconsistent-spacing-between-characters-when-scaling-width.1156967/) for details.

Documentation~/ColorGradients.md

@@ -0,0 +1,42 @@
+# Color Gradients
+
+You can apply gradients of up to four colors to TextMesh Pro GameObjects. When you add a gradient, TextMesh Pro applies it to each character in the text individually. It stores gradient colors as in each character sprite's vertex colors.  
+
+![](images/TMP_ColorGradient_4-Corner-no-legend.png)
+
+_TextMesh Pro text with a four-color gradient_
+
+Because each character sprite consists of two triangles, gradients tend to have a dominant direction. This is most obvious in diagonal gradients.
+
+For example, the dominant direction in gradient below favors the red and black colors in the bottom-left and top-right corners
+
+![](images/TMP_ColorGradient_3-Corner-YBRY_half.png)
+
+When you reverse the gradient colors, so both the top-right and bottom-left corners are yellow, the dominant color changes.
+
+![](images/TMP_ColorGradient_3-Corner-RYYB_half.png)
+
+
+TextMesh Pro multiplies gradient colors with the text's main vertex color (**Main Settings > Vertex Color** in the TextMesh Pro Inspector). If the main vertex color is white you see only the gradient colors. If it’s black you don’t see the gradient colors at all.
+
+## Applying a Gradient
+
+To apply a gradient to a TextMesh Pro GameObject, edit the [Gradient properties](TMPObjectUIText.md#color) in the Inspector.
+
+> [!NOTE]
+> - To apply a gradient to only a portion of the text, use the [gradient](RichTextGradient.md) rich text tag.
+> - To apply a gradient to multiple text objects, use a [gradient preset](ColorGradientsPresets.md).
+
+![](images/TMP_ColorGradientInspector.png)
+
+**To apply a color gradient to a TextMesh Pro GameObject:**
+
+1. Enable the **Main Settings > Color Gradient** property.
+
+1. Set **Main Settings > Color Gradient > Color Mode** to the [type of gradient](ColorGradientsTypes.md) you want to apply.
+
+1. Use the **Main Settings > Color Gradient > Colors** settings to choose colors for the gradient. For each color you can:
+
+  - Click the color swatch to open a [Color Picker](https://docs.unity3d.com/Manual/EditingValueProperties.html).
+  - Use the eyedropper to pick a color from anywhere on your screen.
+  - Enter the color’s hexadecimal value directly in the text field.

Documentation~/ColorGradientsPresets.md

@@ -0,0 +1,36 @@
+# Gradient Presets
+
+Use gradient presets to reuse the same color gradients across text objects. A gradient preset overrides the text’s local gradient type and colors.
+
+You have to store Gradient presets in a specific folder so TextMesh Pro can find them and include them in builds. You can change the folder from the [TextMesh Pro settings](Settings.md#color-gradient-presets).
+
+## Creating gradient presets
+
+To create a gradient preset, choose **Assets > Create  > TextMesh Pro > Color Gradient** from the menu.
+
+This adds a new TextMesh Pro Color Gradient Asset to the Scene, and opens it in the Inspector.
+
+![](images/TMP_ColorGradientPresetCreator.png)
+
+You can then select a [gradient type](ColorGradientTypes.md) from the **Color Mode** dropdown, and set the gradient **Colors**.
+
+## Applying gradient presets
+
+You apply a gradient preset to text from the TextMesh Pro Inspector.
+
+**To apply a gradient preset:**
+
+1. Enable the **Main Settings > Color Gradient** property.
+
+1. Open the Object Picker (circle icon) for **Main Settings > Color Preset**, and choose choose a preset
+
+When you apply a gradient preset, the Inspector overrides the text's gradient type and colors with the values from the preset.
+
+> [!CAUTION]
+> If you modify the gradient settings in the TextMesh Pro Inspector after you apply a preset, it affects the preset itself. Changes affect every object that uses the same preset.
+
+## Removing gradient presets
+
+To remove a gradient preset, open the Object Picker (circle icon) for **Main Settings > Color Preset**, and choose **None**.
+
+When you remove the preset, the text reverts to its local gradient properties.

Documentation~/ColorGradientsTypes.md

@@ -0,0 +1,81 @@
+# Color Gradient Types
+
+You can apply the following types of gradients to text.
+
+- **[Single](#single-color):** A single color that is TextMesh Pro multiplies with the text object's vertex color.
+
+- **[Horizontal](#horizontal-gradients):** A two-color side-to-side gradient.
+
+- **[Vertical](#vertical-gradients):** A two-color up-and-down gradient.
+
+- **[Four Corner](#four-corner-gradients):** A four-color gradient. Each color radiates from one corner.
+
+![](images/TMP_ColorGradientInspector.png)<br/>
+_The TexMesh Pro color gradient settings_ <br/><br/>
+
+The number of colors available in the **Colors** settings depends on the type of gradient you choose. Each swatch corresponds to the color's origin on a character sprite.
+
+The image above shows a the settings for a four color gradient. Each color originates in the corresponding corner of the sprite (top-left, top-right, bottom-left, bottom-right). IT produces the following gradient:
+
+![](images/TMP_ColorGradient_4-Corner-YBRG_half.png)
+
+
+## Single Color
+
+The **Single** gradient type applies a single color.
+
+![](images/TMP_ColorGradient_Single-Y_half.png)
+
+## Horizontal Gradients
+
+The **Horizontal** gradient type applies two colors, and produces a side to side transition between them on each character.
+
+![](images/TMP_ColorGradient_Horiz-YB_half.png)
+
+![](images/TMP_ColorGradient_Horiz-BY_half.png)<br/><br/>
+
+## Vertical Gradients
+
+The **Vertical** gradient type consists of two colors, and produces an up and down transition between the two on each character.
+
+![](images/TMP_ColorGradient_Vert-BY_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_Vert-YB_half.png)<br/><br/>
+
+## Four Corner Gradients
+
+The **Four Corner** gradient type applies four colors. Each one radiates out from its assigned corner of each character.
+
+![](images/TMP_ColorGradient_4-Corner-YBRG_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_4-Corner-YBRO_half.png)
+
+This is the most versatile gradient type. By varying some colors and keeping others identical, you can create different kinds of gradients. For example:
+
+- Give three corners one color and the fourth a different color.
+
+![](images/TMP_ColorGradient_1-Corner-BYYY_half.png)
+
+- Give pairs of adjacent corners the same color to create horizontal  or vertical gradients.
+
+![](images/TMP_ColorGradient_2-Corner-BYBY_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_2-Corner-BBYY_half.png)
+
+- Give pairs of diagonally opposite corners the same color to create diagonal gradients.
+
+![](images/TMP_ColorGradient_2-Corner-BYYB_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_2-Corner-YBBY_half.png)<br/><br/>
+
+- Create horizontal and vertical 3-color gradients with a dominant color at one end and a transition between two colors at the other.
+
+![](images/TMP_ColorGradient_3-Corner-YRYB_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_3-Corner-YYRB_half.png)
+
+- Give two diagonally opposite corners same color and give the other two corners different colors to create a diagonal stripe 3-color gradient.
+
+![](images/TMP_ColorGradient_3-Corner-RYYB_half.png)<br/><br/>
+
+![](images/TMP_ColorGradient_3-Corner-YBRY_half.png)

Documentation~/CustomStyles.md

@@ -0,0 +1,27 @@
+# Styles
+
+Use styles to apply additional formatting to some or all of the text in a TextMesh Pro object. A style is a combination of opening and closing [rich text tags](RichText.md), and can also include leading and trailing characters.
+
+* To define styles, use a TextMesh Pro [style sheet](StyleSheets.md).
+
+* To apply styles to your text, use the [`<style>` rich text tag](RichTextStyle.md) in the text editor.
+
+## Custom styles example
+
+Say you want headings in your text to be big, red, and bold with an asterisk to either side and a line break at the end.
+
+![](images/TMP_StyleSheets_ExampleHeading_Render.png)
+
+That requires several tags for each heading, which makes the formatting cumbersome to maintain, and the text more difficult to read in the editor.
+
+`<font-weight=700><size=2em><color=#FF0000>*Heading*</color></size></font-weight><br>`
+
+It's easier to put all of the markup in a style. The example below shows a  style called `H1`.
+
+![](images/TMP_StyleSheets_ExampleHeading_Inspector.png)
+
+Once you create the style you can format all of your headings with a single `<style>` tag.
+
+`<style="H1">Heading</style>`
+
+Not only does that make the text easier to read in the editor, you can now update all of the headings in your text just by changing the style.

Documentation~/DebugTool.md

@@ -0,0 +1,36 @@
+# Debugging TextMesh Pro text
+
+Use the Text Info Debug Tool to display diagnostic information about a TextMesh Pro GameObject in the Scene view and the Inspector.
+
+For example, you can display lines that indicate font metrics such as the line height, or the offset for superscript and subscript text. This can help you diagnose problems with fonts you import.
+
+![](images/TMP_DebugToolChars.png)
+_The TextMesh Pro debug tool set to show character bounding boxes and font metrics_
+
+>[NOTE!]
+>The debug tool is part of the TextMesh Pro Examples & Extras package. You can install the package from the menu (select **Window > TextMesh Pro > Import TMP Examples and Extras**) or the [TextMesh Pro settings](Settings.md).
+
+To use the debug tool:
+
+1. Open a TextMesh Pro GameObject in the Inspector.
+
+2. [Add](https://docs.unity3d.com/Manual/UsingComponents.html) a **TMP_TextInfoDebugTool** component.
+
+3. From the **TMP_Text Info Debug Tool** section, turn debug [settings](#text-info-debug-tool-properties) on and off. You can see the results in the Scene view.
+
+
+## Text Info Debug Tool properties
+
+![](images/TMP_DebugTool.png)
+
+|Property:|Function:|
+|-|-|
+|**Show Characters**   | Displays each character's bounding box, as well as reference lines for font metrics, in the Scene view.  |
+|**Show Words**    | Displays the bounding box for each word in the Scene view.  |
+|**Show Links**    | Displays the bounding box for each link in the Scene view.  |
+|**Show Lines**    | Displays the bounding box for line of text word in the Scene view.  |
+|**Show Mesh Bounds**    | Displays the bounding box for the entire block of text in the Scene view.  |
+|**Show Text Bounds**    | Displays the boundary of the area that text can occupy, as defined by the font metrics, in the Scene view.  |
+|**Object Stats**   | Shows statistics about the TextMesh Pro GameObject, such as the number of characters, words, lines, and spaces.   |
+|**Text Component**   | Links to the TextMesh Pro GameObject's Text component.  |
+|**Transform**   | Links to the TextMesh Pro GameObject's RectTransform component.  |

Documentation~/Debugging.md

@@ -0,0 +1 @@
+# Debugging TextMesh Pro text

Documentation~/FontAssets.md

@@ -0,0 +1,26 @@
+# Font Assets
+
+To use different fonts with TextMesh Pro, you need to create font assets. TextMesh Pro has its own font Asset format that is distinct from, but related to, [Unity's regular font Asset format](https://docs.unity3d.com/2019.1/Documentation/Manual/class-Font.html). You create TextMesh Pro font assets _from_ Unity font assets.
+
+Every TextMesh Pro font Asset has two sub-Assets:
+
+* **Font atlas:** a black and white or grayscale texture file that contains all of the characters included in the font Asset.<br/><br/>![](images/FontAtlasExample.png)<br/>_Example of a font atlas_
+* **Font material:** a material that controls the appearance of TextMesh Pro text using one of the [TextMesh Pro shaders](Shaders.md).
+
+Font assets must be in a specific folder so TextMesh Pro can find them and include them in builds. To change the default folder for font assets, got to the [TextMesh Pro settings](Settings.md) and set the **Default Font Asset > Path** option.
+
+## Creating Font Assets
+
+To create a TextMesh Pro font Asset, use the TexMesh Pro [Font Asset Creator](FontAssetsCreator.md).
+
+You can also create an empty TextMesh Pro font Asset from the Unity main menu. An empty font asset does not contain any characters by default, you must add them later. To create an empty TextMesh Pro font asset, select a Unity font Asset and then select **Asset > Create > TextMeshPro > Font Asset** from the menu.
+
+## Types of font atlas
+
+Font Assets can have the following types of font atlas:
+
+* **Distance Field:** This type of atlas contains [signed distance field (SDF)](FontAssetsSDF.md) information.<br/><br/>This is the recommended Font Asset type for most applications because SDF atlases produce text that is smooth when transformed.
+
+* **Smooth/Hinted Smooth:** This type of atlas is an antialiased bitmap texture. A Hinted smooth atlas aligns glyph pixels with texture pixels to produce a smoother result.<br/><br/>Smooth atlases work well for static text that is viewed head on, in situations where there is a good correspondence between texture pixels and screen pixels. Transforming text generated from a smooth atlas blurs the text edges.
+
+* **Raster/Raster Hinted:** Raster atlases are un-smoothed bitmap textures. They almost always produce text with jagged, pixellated edges. The Hinted rater atlases align glyph pixels with texture pixels to produce a smoother result.