Class Browser

Revision as of 03:50, 20 April 2013

API Hierarchy
- GSObject *
  - GameObject
    - Browser

This class provides an interface with the Trainz MiniBrowser allowing the programmer to provide a simple HTML interface.
The browser supports a small subset of HTML code.
Muliple browsers are supported.
To create a new Browser, use Constructors.NewBrowser().
To populate with HTML code use either LoadHTMLString or LoadHTMLFile
Refer to the MiniBrowser page for details of supported tags.

Messages

Messages sent to and from Signal objects are listed below:

Major	Minor	Source	Destination
Browser-URL	URL	Browser	Broadcast
Browser-Closed	null	Browser	Broadcast

The URL in a Browser-URL message uses a special hyperlink tag in the form live://linkname.
If your HTML contains the link <a href=live://anthem>Play the national anthem</a> and the user clicks on the link, then the Browser-URL message will take the form of Browser-URL,live://anthem and your script can intercept the message and respond accordingly.
Since messages from Browser objects are always broadcast it is crucial that you ensure that the message is originating from the expected window. You can do this by inspecting the source of the message.
When the user closes the browser window by either clicking on the close button or pressing the Esc key, a message with a Browser-Closed message is broadcast. The Browser object would normally be reset to null in response, so that the browser window disappears.

Constants

Constants defined in this class are:

Browser Window Styles
public define int STYLE_NO_FRAME = 0	Frameless Browser (not in a bordered window).
public define int STYLE_DEFAULT = 1	Default browser style. This is defined by Trainz itself and usually means the browser window will have a framed border.
public define int STYLE_TOOLTIP = 2	Browser with no frame and no facility for user interaction.

General Methods

BringToFront

public native void BringToFront(void)

Parameters

None

Returned Value

None

Syntax

browser.BringToFront();

Notes

Brings the window in front of all other browsers.

GetAsset

public native Asset GetAsset(void)

Parameters

None

Returned Value

The Asset from which this Browser is loading html data and resources.

Syntax

Asset asset = browser.GetAsset();

Notes

The returned asset will be the asset used in the last call to LoadHTMLFile or LoadHTMLString.
If there has been no such call the returned value will be null.

GetWindowVisible

public native bool GetWindowVisible(void)

Parameters

None

Returned Value

True to indicate that the browser is currently visible on screen, false that the browser is hidden.

Syntax

hidden = !browser.GetWindowVisible();

Notes

LoadHTMLFile

public native void LoadHTMLFile(Asset asset, string filename)

Parameters

asset = reference to the asset where the HTML file and other resources are located.
filename = HTML file to load, may include a relative path specifier.

Returned Value

None

Syntax

browser.LoadHTMLFile(resourceAsset,"/html/File-01.html");

Notes

The asset may be of any type, as long as the appropriate files are included in its folder structure.

LoadHTMLString

public native void LoadHTMLString(Asset asset, string htmlData)

Parameters

asset = reference to the asset where any resources required are located.
htmlData = string containing HTML code to load into browser.

Returned Value

None

Syntax

browser.LoadHTMLString(resourceAsset,htmlData);

Notes

The asset may be of any type, as long as the appropriate files are included in its folder structure.

ResetScrollBar

public native void ResetScrollBar(void)

Parameters

None

Returned Value

None

Syntax

browser.ResetScrollBar();

Notes

Moves the scrollbar grip and the html contents to the top.

SetCloseEnabled

public native void SetCloseEnabled(bool enabled)

Parameters

enabled = Set to false to prevent the user from closing the browser, set to true to enable closure.

Returned Value

None

Syntax

browser.SetCloseEnabled(false);

Notes

SetParam

public native void SetParam(int index, string value)

Parameters

index = index of parameter to set.
value = string value to assign to the specified parameter.

Returnd Value

None

Syntax

browser.SetParam(2,"Birmingham New Street");

Notes

HTML code may contain changeable parameters denoted by the placeholder characters $#, where # is a number.
SetParam() intructs the parser to substitute the text in the function parameter for the placeholder when the browser is loaded.

SetScrollEnabled

public native void SetScrollEnabled(bool enabled)

Parameters

enabled = Set to false to prevent the user from scrolling the browser, set to true to enable.

Returned Value

None

Syntax

browser.SetScrollEnabled(false);

Notes

SetWindowStyle

public native void SetWindowStyle(int style)

Parameters

style = One of the Browser Window Style constants defining the type of browser to be provided.

Returned Value

None

Syntax

browser.SetWindowStyle(Browser.STYLE_DEFAULT);

Notes

SetWindowVisible

public native void SetWindowVisible(bool visible)

Parameters

visible = true to show the browser window, false to hide it.

Returned Value

None

Syntax

SetWindowVisible(!GetWindowVisible());

Notes

Browser Size & Position

This group of methods are used to retrieve and set the position and size of the Browser window.
A pixel coordinate system is used with 0,0 being the top left and ScreenWidth - 1, ScreenHeight - 1 being the bottom right.

GetWindowLeft

public native int GetWindowLeft(void)

Retrieves the pixel coordinate of the left hand edge.

GetWindowTop

public native int GetWindowTop(void)

Retrieves the pixel coordinate of the top edge.

GetWindowRight

public native int GetWindowRight(void)

Retrieves the pixel coordinate of the right hand edge.

GetWindowBottom

public native int GetWindowBottom(void)

Retrieves the pixel coordinate of the bottom edge.

GetWindowWidth

public native int GetWindowWidth(void)

Retrieves the width of the window in pixels.

GetWindowHeight

public native int GetWindowHeight(void)

Retrieves the height of the window in pixels.

Parameters

None

Syntax

int width = browser.GetWindowWidth();

Notes

SetWindowLeft

public native void SetWindowLeft(int left)

Sets the pixel coordinate of the left hand edge.

SetWindowTop

public native void SetWindowTop(int top)

Sets the pixel coordinate of the top edge.

SetWindowRight

public native void SetWindowRight(int right)

Sets the pixel coordinate of the right hand edge.

SetWindowBottom

public native void SetWindowBottom(int bottom)

Sets the pixel coordinate of the bottom edge.

SetWindowRect

public native void SetWindowRect(int left, int, top, int right, int bottom)

Sets the pixel coordinates of all four edges in a single call.

SetWindowWidth

public native void SetWindowWidth(int width)

Sets the width of the window in pixels.

SetWindowHeight

public native void SetWindowHeight(int height )

Sets the height of the window in pixels.

SetWindowSize

public native void SetWindowSize(int width, int height )

Sets the height and width of the window in pixels.

SetWindowPosition

public native void SetWindowPosition(int left, int top)

Moves the window to the specified coordinates without affecting its size.

Parameters

left = Pixel coordinate of the left hand edge.
top = Pixel coordinate of the top edge.
right = Pixel coordinate of the right hand edge.
bottom = Pixel coordinate of the bottom edge.
width = Window width in pixels.
height = Window height in pixels.

Returned Value

None

Syntax

browser.SetWindowRect(0,0,200,300);

Notes

SetWindowGrow

public native void SetWindowGrow(int minWidth, int minHeight, int maxWidth, int maxHeight)

Parameters

minWidth,minHeight = Minimum width and height in pixels.
maxWidth,maxHeight = Maximum width and height in pixels.

Returned Value

None

Syntax

browser.SetWindowGrow(100,100,300,300);

Notes

Defines a maximum and minimum height and width that the browser window will be constrained to.

Trainz Object HTML Element

<trainz-object> tags define special browser objects which the user can interact with.
These include a graphic dial, a text entry box or a browser frame and a range of parameters can be applied.

Property	Value	Description
style	string	Type of control, "dial", "text-line" or "browser"
id	string	Name of this object in the browser.
width	integer	Pixel width of area to display object in.
height	integer	Pixel height of area to display object in.
texture	filename	Filename of texture for the object.
min	float	Maximum value of control.
max	float	Maximum value of control.
valmin	float	Minimum possible value the object can be.
valmax	float	Maximum possible value the object can be.
step	integer	Steps in this control.
clickstep	integer	Number of steps per click
value	float	initial default value of the object.

The HTML definition for a dial would be

 <a href="live://dial/dcc" tooltip="Speed control">
   <trainz-object style=dial 
                  width=100 
                  height=100
                  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>
</a>

This HTML code implements the issuing of a Browser-URL message whenever the dial is adjusted by the user.
When the asset script receives the message it will be able to query the control to determine what it needs to do.
Similarly if the script updates any of the dial's properties the HTML graphics will reflect the change.

GetElementProperty

public native string GetElementProperty(string elementId, string propertyId)

Parameters

elementId = Name of HTML element to query.
propertyId = Name of trainz-object property to retrieve.

Returned Value

Current value of specified property.

Syntax

float speed = (float)browser.GetElementProperty("dcc","value"); // returns the current dial position

Notes

All values are returned in string format and must be cast or converted as appropriate.

SetElementObjectProperty

public native void SetElementProperty(string elementId, string propertyId, object value)

I quote N3V's definition verbatim
Sets the property of the named object element in this browser to the given object.

This method is used to assign an object value to the property contained in an element that is in the HTML page this Browser is currently loaded with.

An element in a HTML page is usually a something like a text entry box, dial or button defined by a <trainz-object> tag. Each element has multiple properties in it and this method allows those property items to be set by name.

Parameters:

elementID Name of element to set the property of.
propertyID Property in the element to set. Properties the <trainz-object> tag supports can be used.
value Object the is the value the property will be assigned.

I can't make any sense out of that so you are on your own!

SetElementProperty

public native void SetElementProperty(string elementId, string propertyId, string value)

Parameters

elementId = Name of HTML element to update.
propertyId = Name of trainz-object property to update.
value = New value to set.

Returned Value

None

Syntax

browser.SetElementProperty("dcc","value",(string)speed); // updates the current dial position

Notes

All values must be cast or converted to string format for use in this method.

Trainz Text HTML Element

<trainz-text> tags define text strings which can be updated without the need to reload the page.
These take the form <trainz-text id="speed" text="0mph"></trainz-text>
The text tag specifies the default text that is displayed for the item when the page is initially created.
Once the page is loaded, a script can use SetTrainzText() to provide a dynamic update.

SetTrainzText

public native void SetTrainzText(string id, string text)

Parameters

id = The id of the trainz-text item to update.
text = The string value to provide.

Returned Value

None

Syntax

browser.SetTrainzText("speed","90mph");

Notes

Code Examples

This code illustrates the basics of handling a browser.

class TestBrowser isclass MapObject {

// A global variable to hold the browser object
   Browser browser;

   void OpenBrowser(void) {
   // if the browser doesn't already exist it needs to be created
      if (!browser) browser = Constructors.NewBrowser();
   // define the size and style and load HTML, in this case from a file in the calling asset
      browser.SetWindowPosition(0,0);
      browser.SetWindowStyle(browser.STYLE_DEFAULT);
      browser.SetWindowSize(200,500);
      browser.LoadHTMLFile(GetAsset(),"HTMLSource.html");
   }

   void CloseBrowser(Message msg) {
   // if the browser has been closed we need to destroy the reference to it
      if (msg.src == browser) browser = null;
   }

   void BrowserLink(Message msg) {
   // make sure that we are responding to the correct browser object
      if (msg.src != browser) return;
   // carry out the appropriate response to the link
      string link = msg.minor;
      if (link == "live://anthem") {
         World.Play2DSound(GetAsset(),"God Save the Queen.wav");
      }
      else if (link == "live://travesty") {
         World.Play2DSound(GetAsset(),"Advance Australia Fair.wav");
      }
   }

   public void Init(void) {
      inherited();
   // create handlers for the browser messages
      AddHandler(me,"Browser-URL","","BrowserLink");
      AddHandler(me,"Browser-Closed","","CloseBrowser");
   // open the browser window
      OpenBrowser();
   }

};

Related Methods

Constructors.NewBrowser()

@@ Line 262: / Line 262: @@
 ==Trainz Object HTML Element==
 *<nowiki><trainz-object></nowiki> tags define special browser objects which the user can interact with.
-*These include a graphic dial or a text entry box and a range of parameters can be applied.
+*These include a graphic dial, a text entry box or a browser frame and a range of parameters can be applied.
 <br>
 {{TableHeader|width=50%|margin=15px}}
@@ Line 268: / Line 268: @@
 |bgcolor="#EEEEEE"|'''Property'''||bgcolor="#EEEEEE"|'''Value'''||bgcolor="#EEEEEE"|'''Description'''
 |-
-|style||string||Type of control, "dial" or "text-line"
+|style||string||Type of control, "dial", "text-line" or "browser"
 |-
 |id||string||Name of this object in the browser.