Revision as of 10:16, 4 August 2010

The MiniBrowser is a trivial HTML renderer used for simple layout control within the Trainz game environment. It is specifically not a replacement for a real browser (see Trainz Online instead), is not remotely standards compliant, and does not support a full range of HTML tags. If a tag isn't mentioned here then it is NOT supported. There is no javascript support (TrainzScript is used instead.) The MiniBrowser is used exclusively by the Trainz Browser script object.

Feature requests relating primarily to the MiniBrowser should be placed on the MiniBrowser Feature Requests page.

Trainz HTML is NOT standards compliant and is best thought of as an HTML-alike chosen so users and developers are familiar with the style of syntax being used.

Supported Tags

The MiniBrowser supports the following HTML tags:

HTML

This tag wraps the entire HTML document. No parameters are supported. This tag should be at the top level of the document and should contain a single 'BODY' tag.

Usage:

<html>

...

</html>

BODY

This tag wraps the entire body of the HTML document. The 'scale' parameter is provided to force the document to be rescaled to a specified number of pixels wide, but its usage is strongly discouraged. This tag should exist within the 'HTML' tag and may contain any number of other elements.

Usage:

...

</body>

P (paragraph)

This tag causes the contained elements to be formatted as a separate paragraph. This is similar to prefixing and suffixing the elements with a linebreak. Paragraph tag has no parameters.

Usage:

BR (linebreak)

A forced linebreak. BR has no parameters.

BR is an unclosed tag, unlike XHTML there is no <br /> or </br>. In fact using such a thing will most likely be interpreted as an error by the Trainz HTML parser.

Usage:

...<br>

TABLE

This tag forms a table element. Any number of <TR> (table row) elements may be present within the 'TABLE' tag and that is all it should contain directly. Table height cannot be specified, this can be controlled by setting each <TR> element within the table to add up to the desired table height.

Table does NOT support the following parameters; rules, summary, align. Nor does it support the <TH> element (the same effect can be achieved by making the contents of a <TD> BOLD or even more so by the use of FONT). Table is best thought of as a grid, like that of a spreadsheet or a table inserted into a document. Tables are described by <TR>; a row in a table and <TD>; a cell in a row.

Tables are not askew, meaning if 1 row has 3 cells then all rows will have at least 3 cells, this does not mean the coder must put at least 3 <TD>s in each <TR> it means when formatted for display on screen the html render will organise the table as such (as it is uniform). Furthermore, cells conform to the dimensions of their siblings; meaning a cell has the same width as the widest cell in its column (controllable by width in <TD>) and the same height as the tallest cell in its row (controllable by height in <TR>). This is very important to keep in mind when using tables for formatting/layout purposes.

The documentation on <TR> and <TD> have more information about the use of tables in Trainz HTML. For more info and a place to try out some of these properties of tables try the w3schools table tag page, but remember Trainz HTML is not the same as HTML proper.

All parameters are optional.

cellpadding - specifies the minimum pixel space between the cell wall and its content. Default is 0.
cellspacing - specifies the pixels between cells. Default is 0.
width - specifies the pixel width of the table. If none is given the table will grow to fit its content. If width is given cell content will be wrapped if it would force table width beyond that.
border - specifies the pixel width between the table and content around it. Default is 0.

Usage:

TR

TR is Table Row. This tag forms a single horizontal row of a table. Any number of 'TD' (table data) elements may be present within the 'TR' tag and that is all it should directly contain. <TR> does NOT support the following parameters; align, valign, char, charoff.

All parameters are optional. Height, if specified, will limit how many pixels high this row can be, causing cells to expand in width if they were to approach this height.

When using tables for formatting it is important to remember that cell size is dependent upon both column and row (see <TD> and/or <TABLE> for more info) thus it may be useful to consider creating a <TR> with no data that exists only to set up the size of the columns ie.

<tr> <td width='20'></td> <td width='50'></td> <td width='200'></td> <td width='20'></td>  </tr>

now unless a <TR> with more than 4 <TD>s is created, the formatting for all columns is already done and as this <TR> has no height specified and no data in its <TD> cells it will take up only the space specified by the <TABLE>'s border, cellspacing and cellpadding (default 0).

Usage:

TD

TD is Table Data. This tag forms a single cell within a table row. <TD> does NOT support for following parameters; abbr, axis, char, charoff, headers, height, scope, valign.

Height of a cell is controlled by the tallest cell in the row or by the <TR> height parameter if it is specified.

<TD> is the work horse of tables, as the name implies all contents of a table are contained within a <TD> tag. Anything can be placed within a cell, even a table eg.

<html> <body>
  <table border="1">
    <tr> 
      <td>Some text </td>
      <td>Some text </td> </tr>
    <tr> 
      <td>Some text </td>
      <td>Some text </td> </tr>
    <tr> 
      <td> 
        <table border="1">
          <tr>
            <td>Some text in a sub table </td>
            <td>Some other text in a sub table </td>
          </tr>
        </table>
      </td>
      <td><---Wow thats a sub table over there </td>
    </tr>
  </table>
</body> </html>

coping and pasting the above into the left pane of this Tryit window(open it in a new tab or window) and clicking "Edit and Click me >>" button will show you a table with a table in it on the right hand side.

All parameters are optional.

rowspan and colspan allows this cell to consume the space that would normally be allocated to neighboring cells on the right and bottom sides. Default values are 1, meaning the <TD> spans its own cell and nothing more. Visual example of spanning, but remember Trainz HTML is not the same as HTML proper.
width - specifies the pixel width of this cell, useful for formatting.
align - 'left', 'center', 'right'. (default 'left'.) Controls the horizontal alignment of the content data within the table cell.

Usage:

A

A is the Anchor tag. This tag marks all contained elements as a hyperlink with the specified attributes. Hyperlinked text will be underlined.

Tooltip text will be displayed when the mouse hovers over the hyperlinked elements.

The href is the minor message in a Browser-URL message sent by the Browser to whomever is listening to it. ie. the major="Browser-URL" minor="live://button/horn" message is produced by a hyperlinked button (horn) in the driver user interface.

A hyperlink is considered clicked when the user has pressed and released mouse button 1 while over it.

Usage:

IMG

IMG is the IMaGe tag. This tag displays an image with the specified attributes. Does NOT support the alt or title tags.

All parameters are optional however, the src or the kuid parameter needs to be filled out for anything to show up apart from a fill.

The width and height parameters define the pixel size the image will occupy on screen, these can be made larger or smaller than the image's actual size to zoom, stretch or squash the image as needed. Keep in mind that users don't all use the same resolution, so it is usually best to make pictures either fixed size in a screen position via the use of tables or calculating a pixel size relative to the current resolution.

Usage:

TRAINZ-TEXT

A section of text that can be changed without having to recalculate or reset the entire HTML string in a browser.

In the Driver interface the speed panel shows the selected train's current speed, the current speed limit on its segment of track and the current world time. Below is the speed HTML, which is retrieved via the localisation method described in <FONT>;

<font color=#00FF00 locale='english'><b><trainz-text id='speed' text='0 KM/H'></trainz-text></font>

This specifies green bold text that is bound to an id of "speed". Now in every heartbeat in DriverModule.gs, the currently selected train's speed is calculated and applied to this trainz-text by calling SetTrainzText("speed", "10 kph") [10 kph used only for illustrative purposes] on the browser that contains the speed html.

The id parameter is required to be able to update this section of text via the SetTrainzText browser call. The text parameter does not need to be filled out int HTML can be specified using the SetTrainzText method at a later time.

Usage:

<trainz-text id=? text=?>

B

B is Boldface. Causes any text in contained elements to be rendered as boldface. The bold tag has no parameters.

Usage:

NOWRAP

Suppresses automatic word wrap in the contained elements. The nowrap tag has no parameters.

Usage:

I

I is the Italics tag. Causes any text in the contained elements to be rendered as italic. The italic tag has no parameters.

Usage:

FONT

Causes the specified text attributes to be applied to any text in the contained elements. Text in Trainz HTML does not have to be enclosed in font tags, if none are found around any given text it will receive the default font settings.

Localisation note; the follow statement has special meaning to the Trains HTML parser;

<font locale=generic>A_TAG</font>

When a tag such as this is parsed, Trainz will look in the current users selected language string table of the current asset for a string with the name found between the <font> </font> tags, in this case A_TAG. It will replace the entire statement from here "<font... </font>" to here with what is found in the string table. An example of this at work is in the Driver interface where the camera types are defined in the string tables of the Driver asset config.txt in all available languages so that each camera button has the selected language tooltip for each camera mode.

Usage:

TRAINZ-OBJECT

Documented below under embedded objects. Embedded objects fill the style parameter. The width and height parameters specify the pixel size of the given object, eg. how big a button is.

Usage:

<trainz-object width=? height=? style=?>

Supported Characters

The MiniBrowser parses its input from UTF-8 encoded HTML. The full range of unicode characters may be included without special escape sequences. The following escape sequences are permitted and may be necessary to prevent the characters from being parsed as HTML markup.

  - the HTML non-breaking space character.
> - the "greater than" character (' > ')
< - the "less than" character (' < ')
& - the "ampersand" character (' & ')
" - the "quote" character (' " ')

Embedded Objects

The following embedded objects are supported by the trainz-object tag:

dial

Works like an analogue volume knob. A dial is used in the driver interface, in the dcc panel to control the speed/power of the train. These are its settings;

<trainz-object style=dial width=95 height=95 id='dcc' 
texture='newdriver/dcc/dcc_controller.tga' min=0.1 max=0.9 
valmin=-1.0 valmax=1.0 step=0 clickstep=1 value=0.5></trainz-object>

Driver wraps the dial in an <A> as to receive messages from user interactions with it, it then uses the GetElementProperty("dcc", "value") on the Browser the dial resides in to extract its current value.

Parameters explained;

The style, width, height and id parameters belong to the TRAINZ-OBJECT.
The min and max parameters specify the rotation (as a percent between 0 and 1) the dial can have in the interface. For the driver speed knob its 0.1 to 0.9; imagining this as a clock face this means the dial is allowed to rotate between approximately 7 clockwise around to approximately 5 and vice versa anticlockwise anywhere between 5 and 7. The dial's rotation can never be clockwise between 5 and 7.
valmin and valmax specify the values returned by the dial, that is how its values map to its rotation. Using the clockface analogy again, at approximately 7 the dial will return the value of -1, at approximately 5 it will return the value 1 and at 12 it will return 0.
step specifies the minimum change that can occur in the dial, 0 means it can move completely freely, if step were 0.1 and the user had rotated it by 0.04 no rotation would be registered and the dial would snap back to its previous position.
clickstep TBD
value sets the initial starting position (as a percentage 0 to 1) of its range. 0.5 being half between max and min.

style=dial texture=? min=? max=? valmin=? valmax=? step=? clickstep=? value=?

button

A Button is essentially 8 images; where only 1 is shown at a time determined by the button's on or off-ness and the user's cursor location.

Buttons can be set either 'off' or 'on' by calling SetElementProperty("button name", "value", "1") [for on or "0" for off] on the browser that contains the button. All buttons start in the off state.

Both 'on' and 'off' states have 4 states within them for showing interaction with the cursor. Off is explained below, on is the same replacing "off" with "on";

"off" - button is in the off state and has no cursor interaction.
"off-over" - button is in the off state and the cursor is hovering over the button.
"off-down" - button is in the off state and the cursor has been clicked on the button, is held down (mouse button 1 is down) but the cursor is not (is no longer) hovering over the button meaning the user has dragged the cursor off the button after clicking it.
"off-down-over" - button is in the off state and the cursor is hovering over the button and the cursor has been clicked on it and is being held down (mouse button 1 is down).

The size of a button is determined by the width and height parameters of its containing TRAINZ-OBJECT tag.

Typically a button trainz-object will be contained within an <A> tag giving the appearance that buttons send messages. As buttons do not send clicked messages themselves, they do not directly know when they have been clicked on or off, this must be done manually by listening to the message that will be sent by the anchor tag and changing the buttons state using the SetElementProperty("button name", "value", "1") command on its containing browser.

Usage: ? represent image files within the asset.

style=button id=<button name> off=? off-over=? off-down=? off-down-over=? on=? on-over=? on-down=? on-down-over=?

video

The curiously named MN Session Manager, uses the video trainz object to play some short clips.

The play-on-load tag should be either '1' or '0' being yes or no respectively and it means exactly what it sounds like, should the video start playing once it has loaded.
The is-video-looping is likewise a '1' or '0' value indicating the video should or shouldn't repeat once finished.

style=video play-on-load=? video-filename=? is-video-looping=?

slider

Slider is a horizontal bar similar to a horizontal scroll bar with a linear range of values mapped to it, similar to the dial.

There are several in the video settings menu/asset and those will be used as an example here. The most important attributes are;

min the minimum value the slider represents (far left).
max the maximum value the slider represents (far right).

style=slider min=? max=? page-size=? draw-lines=? draw-marks=? thumb=? thumb-over=? less=? less-over=? more=? more-over=? thumb-width=? thumb-height=?

browser

browser is updated through call to SetElementProperty("component-name","html",sub-browser html string) from the parent browser level. An example of this at work can be found in the waybillmanager.gs

style=browser id='component-name' width=? height=?

driver-menu-button

style=driver-menu-button name=?

graphic-button

style=graphic-button name=? texture_off=? texture_on=?

minimap

style=minimap

text-line

style=text-line background=? align=?

driver-order-bar

Incorrect

Is a very specific case. As the name implies it is the list of driver commands that appears at the bottom of the screen next to the current driver image in Driver. This is already created and managed for you, users probably don't want to make these in any useful way, just to mess around or break things.

style=driver-order-bar

this isn't really accurate. i think you'll find this is already used elsewhere in the game (for example, in the driver command rule?) and in fact possibly isn't used by the main driver interface - it's likely that is not HTML although it's the same underlying control. this is a general-purpose control: the functionality is specific to assigning orders, but it should be fairly flexible what the calling script does with the orders.

clock

style=clock face-texture=? seconds-texture=? minutes-texture=? hours-texture=? seconds-visible=? minutes-visible=? hours-visible=? seconds=? minutes=? hours=?

@@ Line 77: / Line 77: @@
 ==TD==
-TD is Table Data. This tag forms a single cell within a table row. &lt;TD> does NOT support for following parameters; abbr, align, axis, char, charoff, headers, height, scope, valign.
+TD is Table Data. This tag forms a single cell within a table row. &lt;TD> does NOT support for following parameters; abbr, axis, char, charoff, headers, height, scope, valign.
 Height of a cell is controlled by the tallest cell in the row or by the &lt;[[#TR |TR]]> height parameter if it is specified.
@@ Line 112: / Line 112: @@
 *rowspan and colspan allows this cell to consume the space that would normally be allocated to neighboring cells on the right and bottom sides. Default values are 1, meaning the &lt;TD> spans its own cell and nothing more. [http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_table_span Visual example of spanning], but remember Trainz HTML is not the same as HTML proper.
 *width - specifies the pixel width of this cell, useful for formatting.
+*align - 'left', 'center', 'right'. (default 'left'.) Controls the horizontal alignment of the content data within the table cell.
 Usage:
-:&lt;td rowspawn=? colspan=? width=? bgcolor=?>...&lt;/td>
+:&lt;td rowspawn=? colspan=? width=? bgcolor=? align=?>...&lt;/td>
 ==A==

MiniBrowser

Revision as of 10:16, 4 August 2010

Contents

Supported Tags

HTML

BODY

P (paragraph)

BR (linebreak)

TABLE

TR

TD

A

IMG

TRAINZ-TEXT

B

NOWRAP

I

FONT

TRAINZ-OBJECT

Supported Characters

Embedded Objects

dial

button

video

slider

browser

driver-menu-button

graphic-button

minimap

text-line

driver-order-bar

clock

Views

Personal tools

Navigation

Search

Toolbox