Class Browser

From TrainzOnline
Jump to: navigation, search


  • 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.


Contents

Messages

  • Messages sent to and from Browser 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
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)

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.

Some element properties are references to objects, such as the "driver-commands" property of "driver-order-bar"-elements. With this method you can for example pass a DriverCommands object reference to the driver-order-bar element. Also an embedded browser can receive an Asset reference for it's "asset" property via this method. This will change the asset where images are loaded from.



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()

Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_Browser&oldid=29705"
Personal tools