-
Notifications
You must be signed in to change notification settings - Fork 29
Formatted Rich Text
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:
(in a config file)
text = RCS
This will evaluate to the text "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.
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()
Because variables in MAS are evaluated as snippets of Lua, the RasterPropMonitor convention of separating variables with spaces has been replaced with using a semi-colon ';':
text = Ap: {0:#####0.0}km / Pe: {1:#####0.0}km $&$ fc.GetApoapsis() / 1000; fc.GetPeriapsis() / 1000
Note in this case that in addition to using two variables, we are also converting the Ap and Pe from meters to km. Mathematical expressions are allowed in variables.
To support the Prop Config tool and the XML data files it uses, the token $#$ may be used as the variable separator:
text = Ap: {0:#####0.0}km / Pe: {1:#####0.0}km $#$ fc.GetApoapsis() / 1000; fc.GetPeriapsis() / 1000
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
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
[#ffffff]Some Text {0} $&$ fc.GetPersistent("SomePersistent")
if the default text color is already white).
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,
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.
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 have not been implemented. 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. Since MAS allows mathematical operations on variables, and fc.Remap() can likewise convert variables to the range [0, 1], this restriction should not be excessive.
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.