-
Notifications
You must be signed in to change notification settings - Fork 16
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.
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. The tag remains active until the end of line, to switch back just insert another one - [#ffffffff]
would be the 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.
The standard String.Format is extended with several extra format options to handle KSP-specific formatting needs:
That is, kilo-meters, mega-meters, giga-meters, etc, which is very handy for altitudes 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.
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. Notice that all of this refers to a "year" that is 365 days long, a "day" that is 24 hours long, etc -- actual orbital period of Kerbin is not used for Kerbal calendar anywhere in the game.
- KDT -- format prefix
-
- -- 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.
- 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, i.e. 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. 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.
For a full list of variables you can use, see Defined variables.