-
Notifications
You must be signed in to change notification settings - Fork 69
Writing page definition files
Page definition files are normal text files in UTF-8 encoding, lines are separated by normal line break characters. Both Windows and Linux/Mac line breaks work - just don't mix them in one file. Extension can be anything, but .txt is recommended. (KSP may take offence if it's .cfg) The real power of screen definitions comes from the [String.Format][1] C# function which is applied to them: various pieces of data can be inserted anywhere into the text. For a quick reference of how String.Format works and some examples you can see this handy blog post. An example: [1]: http://msdn.microsoft.com/en-us/library/system.string.format(v=vs.90).aspx
Altitude is {0:##0.00} $&$ ALTITUDE
The special sequence of symbols "
While debugging your page definition, it helps to know that the plugin reloads page definitions from disk, (the ones stored in files, at least) every time it is instantiated, which is every time the vessel is loaded -- which happens if you go back to the space center and return, or even simply switch to an out of range vessel and back. BEWARE: This is not true of various *.cfg files that make up the monitor configuration, for changing which you will want to reload GameDatabase through the debug menu.
Remember, that tab characters (ASCII 0x9, that is) are illegal (just what should the tab width be anyway?) and if your editor replaces your spaces with tabs, you should punish it appropriately.
You can modify output in various ways by using tags, which are sequences of characters in square brackets. Notice that tags are processed after the variables are already out of the equation, so you can do stuff like [#{0:"ffffff";"ff0000";"00ff00"}]{0}[#ffffff] to paint a number different colors depending on whether it's positive or negative, for example.
The font can be tinted on the fly into any RGBA color. To do this, insert a tag in the form of [#rrggbbaa] where rr,gg,bb and aa are color components presented in hexadecimal just like in HTML colors. You can use the abbreviated [#rrggbb] variant, in which case the alpha component is assumed to be 'ff'. The tag remains active until the end of line, to switch back just insert another one - [#ffffffff] would be the default. At the beginning of the line, the color is reset to default. For a more detailed introduction into HTML colors consult a HTML color chart -- remember that it does not generate alpha as HTML only uses it occasionally, you need two extra symbols at the end which are the alpha -- "FF" is completely opaque, "00" is completely transparent.
Beware that if your font is natively bright white in the font bitmap, brighter colors might not result in a noticeable color change at all. For best results, make your font bitmap a 50% grey if you wish to use tinting throughout. Notice that this applies to alpha levels as well.
Sometimes, you may find yourself with a need to shift the symbols by a specific number of pixels, rather than a full symbol position, which is especially important if you're drawing them on top of a graphical background of one kind or another. To do this, you can use nudge tags in the form of [@x<offset>] and [@y<offset>], i.e. [@x-8] will nudge the symbols 8 pixels to the left and [@y8] will nudge the line 8 pixels down. There is no limit to how far you can nudge them.
Nudge tags introduce a permanent offset to the symbols printed after them, and remain in effect until the end of line, or until reset - [@x0] or [@y0] will reset the respective nudge offsets to zero.
You can also print text in superscript and subscript, which is accomplished by squishing the font by half vertically and printing it in the upper or lower half of it's normal position, by using the [sup] tag for superscript and [sub] for subscript, with [/sup] and [/sub] resetting text to normal. Like all other tags, superscript and subscript only remain in effect until the end of line.
In a similar fashion, you can print half width characters using [hw] tag and double width characters using [dw] tag. [/hw] and [/dw] tags reset text to normal.
A monitor can have more than one font defined. To switch between them, use the [font<number>] tags. The font defined in the fontTransform option is always [font0], while others are in order of appearance of their extraFont configuration options in the file. Font is always reset to the default at the beginning of the line.
Sometimes you may find yourself with the need to print symbol sequences which would otherwise get recognized as tags, i.e. '[@' or '[#'. In this case, you can escape the opening square bracket by taking into a separate pair of square brackets.
The standard String.Format is extended with several extra format options to handle KSP-specific formatting needs, which are listed here. You can still use the >0;<0;0 format splitters, but beware, the resulting behaviour might not be entirely consistent with standard string.format selection.
That is, kilo-meters, mega-meters, giga-meters, etc, which is very handy for altitudes, distances and speeds.
{0:SIP_05.2}m/s $&$ VARIABLE
This will format a value with SI prefixes, i.e. this way 65000m can become 65km and your values can squeeze into smaller fields of fixed width.
Assuming VARIABLE is a number, it will be formatted to fit into 5 characters, with no more than .2 digits after the decimal point. Since it includes a _ marker, a space will be inserted between the SI prefix and the number, and since the number of characters starts with a 0, it will be padded to the right with zeroes. 0, _ and the post-decimal point specifier are optional -- if there's no zero, it will be padded to the right with spaces, if there's no decimal point, the plugin will decide how many digits after decimal are permissible.
Converting units by a fixed factor. U2K converts a unit to kilo-units (for instance, it would display ALTITUDE in km instead of meters), while U2M converts a unit to milli-units (for instance, displaying DYNAMICPRESSURE as Pa instead of kPa).
{0:U2K####0.00}km $&$ RADARALTOCEAN
This will format an angle into degrees, minutes and seconds, inserting appropriate characters denoting those if required:
- DMS -- format prefix
- N,S,E,W -- Any of these characters will be replaced by the correct character depending on the sign of the value. N and S will mean latitude is used, E and W will mean longitude is used.
- d -- degrees, no padding.
- dd -- degrees, zero padding.
- m -- minutes, no padding
- mm -- minutes, zero padding.
- s -- seconds, no padding.
- ss - seconds, zero padding.
- + -- replaced by the appropriate degree-minute-second symbol, if encountered immediately after d, m or s.
All other characters will be passed unaltered. Example usage:
{0:DMSd+ mm+ ss+ N} -- will format a latitude value exactly
like the old LATITUDE_DMS variable would.
{0:DMSd+ mm+ ss+ E} -- will format a longitude value exactly
like the old LONGITUDE_DMS variable would.
Kerbals have some special needs regarding the display of time -- for example, it makes no sense whatsoever to speak of Kerbal months. To fit those special needs, the KDT formatter was introduced.
The length of the year and day observes game settings -- If your game settings are set to observe true Kerbin rotational time, a 'day' is 6 hours long and a 'year' is 426 days long. If they aren't, a 'year' is 365 days long and a 'day' is 24 hours long.
- KDT -- format prefix for displaying UT
- MET -- Alternate format prefix for MET
- + -- Replaced by a plus sign if the time span is positive and a minus sign if the time span is negative.
- - -- Replaced by a space if the time span is positive, and a minus sign if the time span is negative.
- y -- Number of years.
-
d -- Number of days. When using the
KDTprefix, one is added to this number so the display matches the KSP UT day (so Year 1 Day 1 appears as 01:001, instead of 01:000). When usingMET, the day number is unchanged. - D -- Number of whole days, i.e. assuming that there will be no years in the output.
- h -- Number of hours.
- H -- Number of whole hours, i.e. assuming that there will be no days or years in the output.
- m -- Number of minutes.
- M -- Number of whole minutes, i.e. assuming that there will be no hours or above in the output.
- s -- Number of seconds.
- S -- Number of whole seconds, i.e. assuming that we're only showing seconds.
- f -- Fractional seconds. Repeating this character will produce further sub-second resolution.
All other characters are passed unchanged. Using one specifier character will insert the entire number, without padding, no matter how long it ends up being. Repeating the specifier character more than once means that the resulting number will be padded with zeroes to produce a string of that many characters. Characters are not trimmed, so if there are more digits than would fit in the space given, they will overflow. Examples:
{0:KDTyy:ddd:hh:mm:ss.f} -- Most time values were previously returned like this: no sign,
two digit year, three digit day, two digit hour, two digit minute,
two digits second, one digit fractional second.
{0:KDTy:d:h:m:s.f} -- Will show the same without padding values with zeroes.
This formatter takes a numeric value and produces a string of a given length, proportionally filled with one of two characters depending on it's arguments... That needs more elaboration.
Suppose you have SYSR_ELECTRICCHARGEPERCENT variable, which goes from 0 to 1 and shows the percent of total electric charge you have left, and you have exactly 50% of it remaining. You feed it into {0:BAR,10} format string, and get the string ===== (padded to ten characters long exactly). As your electric charge dwindles, the proportion of the string filled with = will also dwindle.
The full format definition is like this:
BAR[<bar character>[<empty character>[<trailer character>]]],<total length>[,<minimum>[,<maximum>]]
Examples:
BAR,10,10000,200000 -- string of length 10, scale is from 10000 to 200000.
BAR =,10,0,200 -- bar is drawn with spaces, = is used for the empty space.
BAR~,10,0,200 -- bar is drawn with tildes.
BAR~ |,-10,0,200 -- bar is drawn right to left, with tildes, and terminated
with a pipe character.
BAR,10 -- Just the simple bar 10 characters long.
- bar character is the character the 'full' portion of the bar will be printed with.
- empty character is the character the 'empty' portion of the bar will be printed with.
- trailer character is the character that will be the last (or first, if the bar is reversed) character of the filled portion of the bar.
The total length of the string can be given as negative. If that is the case, the bar will be reversed from the normal empty end on the left, full end on the right. If minimum and maximum ends of the scale aren't given, they're assumed to be 0 and 1 respectively. If bar character and empty character are not given, they are = and space respectively. If trailer character is not given, there is no trailer character.
For a full list of variables you can use, see Defined variables.