Formatted Rich Text - MOARdV/AvionicsSystems GitHub Wiki

Avionics Systems uses Formatted Rich Text as originally defined in RasterPropMonitor with some minor changes.

Static or unchanging text such as might be used for labels on controls and instruments may be listed directly:

text = RCS

This config will display RCS.

Text may contain variables that are evaluated, allowing for changing text. This text might be used for digital displays or for monitors, for instance. Text expressed in this way follows the C# standards for formatting, with some extensions to the formatting string, as detailed below. Because of the way C# processes text, formatting strings must use the characters <= and => to mark format substitution. Using { and } will often lead to parsing errors.

To separate the formatting text from the variable list, the token $&$ is inserted at the end of the formatting string, before the variable list:

text = Altitude: <=0:#####0.0=>m $&$ fc.GetAltitude()

If more than one variable needs to be evaluated, use the semi-colon ; character to separate the variables:

text = Ap: <=0:#####0.0=>km / Pe: <=1:#####0.0=>km $&$ fc.GetApoapsis() * 0.001; fc.GetPeriapsis() * 0.001

In this example, we are also converting the Ap and Pe from meters to km. Mathematical expressions are allowed in variables. When possible, use multiplication instead of division - it requires less processor overhead to multiply than it does to divide.

To support the Prop Config tool and the XML data files it uses, the token $#$ may be used as the variable separator instead of $&$:

text = Ap: {0:#####0.0}km / Pe: {1:#####0.0}km $#$ fc.GetApoapsis() * 0.001; fc.GetPeriapsis() * 0.001

MAS accepts either token interchangeably.

Monitor pages can use layout info stored in text files, like RasterPropMonitor page definition files. In a page definition file, the text rows use the end-of-lines to separate rows of text. In an inline text definition, such as the TEXT_LABEL of a MASComponent, end-of-line doesn't work. Instead the token $$$ may be used to indicate a new line. Note that this token is translated directly into a new line character, so the following would not work:

text = ALT : <=0:#####.0=>m $$$ RALT: <=1:#####.0=>m $&$ fc.GetAltitude(); fc.GetRadarAltitude()

That text would be converted to

ALT : <=0:#####.0=>m 
RALT: <=1:#####.0=>m $&$ fc.GetAltitude(); fc.GetRadarAltitude()

which will generate a string formatting exception, since there is no variable on the first row. Instead, the text needs to be defined as

text = ALT : <=0:#####.0=>m $&$ fc.GetAltitude() $$$ RALT: <=0:#####.0=>m $&$ fc.GetRadarAltitude()

Text may include expressions that allow for additional effects. These expressions are enclosed in square brackets [ and ]. Rich Text is processed after variables have been evaluated, so it is possible (and common) to use variables inside rich text tags.

Rich text containing square brackets is more computationally expensive to process when it is updated, so it should be used only where its effects are needed (for instance, don't do

text = [#ffffff]Some Text <=0=> $&$ fc.GetPersistent("SomePersistent")

if the default text color is already white - set the textColor to white using the node configuration).

Text color can be changed on the fly by using the color tag. Colors are expressed as hexadecimal RGB or RGBA sequences, similar to how colors are often expressed within HTML pages. For instance,

text = This is [#ff0000]RED[#ffffff] text.

will display "This is" in the default text color, "RED" in red, and "text." in white. Once a color token has been used, it is applied until another color token is found, or the text reaches the end of the line. The alpha values are optional, and they default to 255 (ff) if they are omitted. There is no option to reset the color to the default text color within a line of text once it's been changed.

Newline tags may be used to create vertical text with optional variable vertical advances. This feature is only available with the fixed-width TEXT nodes used on a MASMonitor MFD. The [n] tag will advance the line by one, and it will back up the cursor by one character unless other [n] tags immediately preceded the current [n]. The [n#] tag will also back up the cursor by one character, but it will advance the line by the number of rows indicated in the '#'. For example, [n2] move the cursor down by two lines of text. [n-1.5] will move the cursor up by 1.5 lines. The newline tag does not cancel X and Y nudge tags, so a block of vertical text created with [n] tags may be moved around the screen using only a single X and Y tag. Likewise, this node does not cancel other text tags, such as color and style.

Text position can be changed using nudge tags. On an MFD MASMonitor, a nudge moves the text by a number of pixels from its default position (the position the character would have been drawn at using [@x0][@y0]). Positive X values move the text to the right, negative values to the left. Positive Y moves the text down, negative moves up. Using [@x0][@y0] moves the text back to its normal position. Variables can be used for the nudges, so one common technique is to use nudges to move text on a monitor, such as cues for docking alignment or altimeter strips. Nudges reset to zero at the end of a row of text.

Note that a TEXT node on an MFD can also use variables to control the text's position. This has the advantage of being much less computationally expensive, since MAS does not have to regenerate all of the characters in the text. If all you need to do is move a block of text around, use a variable position. Try to use nudge tags only for nudging part of a text block.

With Label Text in a MASComponent, the nudge moves the text by an amount based on the resolution of the underlying font, but the distance is affected by scaling and other factors, so it may require some tuning to position it correctly. Note that the nudge tags do not affect text alignment computations, so results may not be ideal with center-justified or right-justified text that uses x-nudges.

These tags allow the use of bold or italic font styles for fonts that support those styles. Like the other nudges, these modifiers reset at the end of the row of text. However, they can be terminated early using an HTML-style token.

text = This text is [b]bold[/b] [i][b]and[/b] italic[/i].

Style tags do not nest: the text after [b][b][/b] will not be bold. Open and close bold and italic tags can be intermingled - [b]B[i]BI[/b]I[/i] is perfectly legal.

These tags shrink or stretch text horizontally. Half-width [hw] means each character is half as wide as normal, and the character advances 1/2 the amount as well. Double-width [dw] means the text is twice as wide. Each option is terminated using an HTML-style closing tag (eg [/hw] or [/dw]).

Since these tags do not follow strict HTML guidelines, either [/hw] or [/dw] will cancel either half-width or double-width text. A [hw] or [dw] tag will override a prior [hw] or [dw] tag on the same text row.

Width tags are reset at the end of a line.

These tags were available in RPM, but they are not available in MAS. MAS will silently ignore them and remove them from displayed text.

Like RPM, MAS supports some custom string formatting.

Numbers may be formatted with SI Prefixes (k, M, G, etc). The prefixes are automatically added to the end of the number, with a blank character when there is no prefix. The formatting string is otherwise treated like a regular formatting string:

Format        12.34     123456
<=0:SIP##0=>  '12 '     '123k'
<=0:SIP000=>  '000 '    '123k'
<=0:SIP0.00=> '12.34 '  '123.46k' (due to rounding)

Times may be converted to custom date/time formatting using KDT and MET. The difference between the two formats is in the treatment of the year ('y' and 'Y') and days of the year (lower-case 'd'): KDT treats it as a calendar date, with the first year of the game identified as Year 1, and the first day of the year identified as Day 1. The MET prefix start both at 0. The two are otherwise identical. The formatting automatically adjusts to Earth time or Kerbin time depending on game settings.

The following reserved characters have special meaning in a date. All other characters are passed through unchanged. Repeating one of the letters will zero pad that field (for Year 1, 'YYYY' will be '0001').

• '+': Insert a '+' if the date is positive, or a '-' if it is negative.
• '-': Insert a '-' if the date is negative, or do nothing if it is positive.
• 'Y', 'y': Insert the year.
• 'D': Insert the number of days, ignoring years (so 400 in Earth days will be 400, not 35).
• 'd': Insert the number of days, accounting for years.
• 'H': Insert the number of hours, ignoring days and years.
• 'h': Insert the number of hours, accounting for days.
• 'M': Insert the number of minutes, ignoring hours.
• 'm': Insert the number of minutes, accounting for hours.
• 'S': Insert the number of seconds, ignoring minutes.
• 's': Insert the number of seconds, accounting for minutes.
• 'f': Insert fractions of a second.

Treat the variable as either Latitude or Longitude, depending on the prefix. If a '0' follows the LAT or LON keyword, degrees are zero padded. If the value is illegal (>90 or <-90 for Lat, >180 or <-180 for Lon), it is clamped to the nearest limit.

For Latitude, the format is DD+ MM+ SS+ @. For Longitude, the format is DDD+ MM+ SS+ @.

• D = degrees. If LAT0 or LON0 is used, the degrees are zero padded. Otherwise, they are padded with blanks.
• M = minutes of arc. Minutes are always zero padded.
• S = seconds of arc. Seconds are always zero padded.
• • = symbol. The appropriate symbol °, ', or ".
• @ = The letter N or S for latitude, or E or W for longitude.

This format is similar to the RPM format specifier in that it generates a bar graph using text characters, such as

[======    ] 60%

It differs in usage, with fewer configuration options in order to simplify the format. The biggest difference is that the input number must range between 0 and 1. Variables that do not fall in that range are clamped. If the value being displayed does not fall into the required range, it can be scaled or converted using mathematical operations or fc.Remap().

The format is specified as

BAR,cc,#

Where cc are the two characters used for filled and empty blocks, respectively, and # is an integer that tells BAR how long the total bar graph should be. Some examples:

[<=0:BAR,= ,10=>] <=1:##0=>% $&$ fc.GetThrottle(); fc.GetThrottle() * 100

will generate a 10 character bar graph like the one displayed at the top of this section. To make it easier to read, we could replace the whitespace with another character, such as

[<=0:BAR,=-,10=>] <=1:##0=>% $&$ fc.GetThrottle(); fc.GetThrottle() * 100

which would result in

[======----] 60%

Note that, in this case, we have to use fc.GetThrottle() in two variables, since it returns a value between 0 and 1, but we also want to display the throttle setting as a numeric value between 0 and 100 (although using the P format specifier for the percentage display would allow us to use a single variable).