Text Formatting: Difference between revisions

From Resonite Wiki
m fix typo
→‎Format Strings: locale warning.
 
Line 281: Line 281:


==Format Strings==
==Format Strings==
Format strings are a string of characters you can use in certain components and protoflux nodes to format values (like float or DateTime) as strings in different ways. The syntax for the format strings is from the [https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting#format-string-component .NET formatString component]. The output is also determined by your locale/language, which means the output of the formatting could be different locally for each user, depending on their locale.
Format strings are a string of characters you can use in certain components and protoflux nodes to format values (like float or DateTime) as strings in different ways. The syntax for the format strings is from the [https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting#format-string-component .NET formatString component]. The output is also determined by your locale/language, which means the output of the formatting could be different locally for each user, depending on their language setting.
 
Consider provide explicit [[Type:IFormatProvider|locale]] if you do not like that behavior: decimal point and digit group separator may change per it!


===Components===
===Components===

Latest revision as of 19:27, 25 September 2024

This article or section is a Stub. You can help the Resonite Wiki by expanding it.



Resonite supports a variety of text formatting tags. These tags can be added to text within various Components to provide additional formatting options.

Formatting

The text formatting system for styling text is inspired by HTML but isn't intended to be strictly compatible with standard HTML. The basic idea is that a section of text can be enclosed inside a pair of matching tags. For example, the <b> tag applies bold style: Are we <b>not</b> men? This would result in: Are we not men?

As the example shows, the tags are just pieces of text inside the angle brackets < and >.

Place the opening tag at the beginning of the section. The text inside the tag denotes its name (which in the example is just b). Place another tag at the end of the section. This is the closing tag. It has the same name as the opening tag, but the name is prefixed with a slash / character. Every opening tag must have a corresponding closing tag. If you don't close an opening tag, it's okay: the style continues to the end of the text.

The tags are not displayed to the user directly but are interpreted as instructions for styling the text they enclose.

Parameters

Some tags have a simple all-or-nothing effect on the text but others might allow for variations. For example, the color tag needs to know which color to apply. Information like this is added to tags by the use of parameters. For example: We are <color=green>Devo</color>..

Note that the ending tag doesn't include the parameter value.

Tag parameters cannot include extra characters. For example, this: We are <color =green>Devo</color>. does not work because of the space before the = character.

Quirks

  • Unlike HTML, tags don't necesarily have to fully encapsulate one another, so writing <b>bold text<i>bold italic text</b>italic text</i> is totally fine.
  • All tags can have trailing spacebars meaning that writing a tag such as <b   >Bold Text</b> is totally fine.
  • For parameters, instead of writing an equal sign it's possible to use a space bar so writing <color red>Red Text</color> is totally fine.
  • Tags that don't accept parameters can still have the parameter separator (=) and still parse so writing <b=>Bold Text</b> is totally fine.

Tag List

Tag Example Description
align <align=left>Text</align> Sets text alignment. Valid arguments are left, right, center and justify.
allcaps <allcaps>Text</allcaps> Renders lowercase characters as small uppercase characters. Same as the smallcaps tag.
alpha <alpha=#80>Text</alpha> Renders text with a specific transparency level (#FF is fully opaque, and #00 is fully transparent). Because of a bug alpha can accept color names like this <alpha=red>Text</alpha>.
b <b>Text</b> Shows text in boldface.
br <br> Inserts a line break into the text.
closeall </closeall> Closes all format specifiers that came before this tag.
closeallblock <b><closeallblock><i>Text</closeall></closeallblock></b> Creates a block for the above </closeall> tag to operate in. As shown in the example, prevents the <b> tag from being closed until explicitly closed with </b>.
color <color=#FF0000>Text</color> Sets the color of the text according to the parameter value. The color can be specified in the traditional HTML format: #rrggbbaa where the letters correspond to pairs of hexadecimal digits denoting the red, green, blue and alpha (optional) values for the color. For example, cyan at full opacity would be specified by color=#00ffffff. You can specify hexadecimal values in short form; #FF0000 is equivalent to #F00. You may also use the names of colors, such as red, green, blue and so on. A list of all valid colors can be found in the Color Names section.
font <font="Font Name">Font (by name)</font> OR <font=1>Font (by index)</font> Renders the text with a specific font, specified either by index or by name. This requires the usage of a FontCollection component.
glyph <glyph name="test"> Renders a Sprite. Same as the sprite tag. Sprites insert an image into text, they ignore colors. This requires both FontChain & DynamicSpriteFont Components. Sprites in Resonite use a SpriteURL which is a direct link to the image and the Sprite Name. To prevent content from breaking in case your link breaks. It's recommended to use images you Know will not expire, like saving the image to your inventory where you can keep it safe. Example of using a sprite would be <sprite name=baguette> -- You can customize their position & separation using DynamicSpriteFont. This can be changed per sprite.
gradient <gradient=#F00,#00F>Text</gradient> The gradient tag does not do anything, but it exists in the code and parses correctly when written in game. Presumably it would have created a horizontal gradient over the text, using the specified color values.
i <i>Text</i> Shows text in italics.
line-height <line-height=200%>Line Height</line-height> Changes the line height of the text by the specified percentage (200% means the line height will be twice as large).
lowercase <lowercase>Text</lowercase> Forces all characters to be lowercase
mark <mark=#ffff00aa></mark> Used to highlight text in an RGBA hex color. Hex codes can be written in short form, if the alpha values are omitted the default value will be 25% alpha.
nobr <nobr>Text</nobr> Prevents automatic line breaks from being inserted. This can be useful if you want words to stay together and not be separated by word wrapping.
noparse <noparse>Text</noparse> OR <noparse=4>Text Prevents the contents of the tag from being parsed as rich text. Alternatively instead of a closing tag a number can be specified inside of the opening tag which will prevent the N next characters from being parsed.
s <s>Text</s> Shows text with a line through it, also known as strikethough.
size <size=16>Text</size> OR <size=80%>Text</size> Sets the size of the text. It's recommended to use the relative version of this tag, as the absolute units can be vastly different when applied in physical ui (TextRenderer component) and UIX canvases (Text component).
smallcaps <smallcaps>Text</smallcaps> Same as the allcaps tag.
sprite <sprite name="test"> Same as the glyph tag.
sub <sub>Text</sub> Displays the text in subscript
sup <sup>Text</sup> Displays the text in superscript
u <u>Text</u> Shows text with a line beneath it, also known as underline.
uppercase <uppercase>Text</uppercase> Forces all characters to be uppercase.

Color Names

The color tag (and alpha tag) can accept colors by name, the list of allowed color names and their values is as follows:

Name Value Color
clear rgba(0,0,0,0)
white rgb(1,1,1)
gray rgb(0.5,0.5,0.5)
black rgb(0,0,0)
red rgb(1,0,0)
green rgb(0,1,0)
blue rgb(0,0,1)
yellow rgb(1,1,0)
cyan rgb(0,1,1)
magenta rgb(1,0,1)
orange rgb(1,0.5,0)
purple rgb(0.5,0,1)
lime rgb(0.75,1,0)
pink rgb(1,0,0.5)
brown rgb(0.25,0,0)

Additionally it is possible to use the Branding colors. These colors can also be found in the PlatformColorPalette component.

A list of all possible values using this method is listed here:

Name Hex Code Color
neutrals.dark #11151d
neutrals.mid #2b2f35
neutrals.light #4a4a4d
hero.yellow #f8f770
hero.green #59eb5c
hero.red #ff7676
hero.purple #ba64f2
hero.cyan #61d1fa
hero.orange #e69e50
sub.yellow #484a2c
sub.green #24512c
sub.red #5d323a
sub.purple #492f64
sub.cyan #284c5d
sub.orange #48392a
dark.yellow #2b2e26
dark.green #192d24
dark.red #1a1318
dark.purple #241e35
dark.cyan #1a2a36
dark.orange #292423

Format Strings

Format strings are a string of characters you can use in certain components and protoflux nodes to format values (like float or DateTime) as strings in different ways. The syntax for the format strings is from the .NET formatString component. The output is also determined by your locale/language, which means the output of the formatting could be different locally for each user, depending on their language setting.

Consider provide explicit locale if you do not like that behavior: decimal point and digit group separator may change per it!

Components

Protoflux Nodes

Format Strings Syntax

Standard Numeric Format Strings

Specifier Name Description Example Input Example Output
"C" or "c" Currency Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

  • Input Value: 20.501
  • Format String: {0:c}
$20.50
  • Input Value: 20.501
  • Format String: {0:c3}
$20.501
"D" or "d" Decimal Result: Integer digits with optional negative sign.

Supported by: Integral types only.

Precision specifier: Minimum number of digits.

Default precision specifier: Minimum number of digits required

  • Input Value: 1234
  • Format String: {0:d}
1234
  • Input value: -1234
  • Format String: {0:d6}
-001234
"E" or "e" Exponential (scientific) Result: Exponential notation.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: 6.

  • Input Value: 1052.0329112756
  • Format String: {0:e}
1.052033E+003
  • Input value: -1052.0329112756
  • Format String: {0:e2}
-1.05e+003
"F" or "f" Fixed-point Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by NumberFormatInfo.NumberDecimalDigits. Usually 2.

  • Input Value: 1234.567
  • Format String: {0:f}
1234.57
  • Input value: 1234
  • Format String: {0:f1}
1234.0
"G" or "g" General Result: The more compact of either fixed-point or scientific notation.

Supported by: All numeric types.

Precision specifier: Number of significant digits.

Default precision specifier: Depends on numeric type.

  • Input Value: 0.01
  • Format String: {0:g}
0.01
  • Input value: 200.2
  • Format String: {0:g2}
2e+02
"N" or "n" number The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by NumberFormatInfo.NumberDecimalDigits. Usually 2.

  • Input Value: 12345
  • Format String: {0:n}
12,345.00
  • Input value: 4567.22
  • Format String: {0:n1}
4,567.2
"P" or "p" Percent Result: Number multiplied by 100 and displayed with a percent symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

  • Input Value: 0.451
  • Format String: {0:p}
45.10%
  • Input value: 0.98221
  • Format String: {0:p0}
98%
  • Input value: 0.22222
  • Format String: {0:p1}
22.2%
"R" or "r" Round-trip The round-trip ("R") format specifier attempts to ensure that a numeric value that is converted to a string is parsed back into the same numeric value. This format is supported only for the float and double types in Resonite. It is recommended to use the "G" specifier instead.
  • Input Value: 2345.001
  • Format String: {0:r}
2345.001
  • Input value: 123456789.123
  • Format String: {0:r}
123456789.123
"X" or "x" Hexadecimal Result: A hexadecimal string.

Supported by: Integral types only.

Precision specifier: Number of digits in the result string.

Capitalization of the 'x' affects the capitalization of non-digit hex characters.

  • Input Value: 123
  • Format String: {0:x}
7b
  • Input value: 123
  • Format String: {0:X}
7B
  • Input value: 31
  • Format String: {0:X4}
001F

Custom Numeric Format Strings

These format strings give you a way to customize how a value is formatted as a string, instead of the preset standard ones from the previous table.

Specifier Name Description Example Input Example Output
"0" Zero placeholder Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string.
  • Input value: 1234.1
  • Format string: {0:0000}
1234
  • Input value: 1234.1
  • Format string: {0:00000.0}
01234.1
"#" Digit placeholder Replaces the "#" symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string.

Note that no digit appears in the result string if the corresponding digit in the input string is a non-significant 0. For example, 0003 with format {0:####} -> 3.

  • Input value: 1234.5678
  • Format string: {0:#####}
1235
  • Input value: 0.3737
  • Format string: {0:#.##}
.37
"." Decimal point Determines the location of the decimal separator in the result string. Shown in other examples

Related issues