Class Browser

Revision as of 17:37, 12 April 2019 (view source) Callavsg (Talk | contribs) (→‎SetElementObjectProperty) ← Older edit		Revision as of 17:39, 12 April 2019 (view source) Callavsg (Talk | contribs) (→‎SetElementObjectProperty) Newer edit →
Line 343:		Line 343:
	Some element properties are references to objects, such as the "driver-commands" property of "driver-order-bar"-elements.		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.		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.	+	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 (It might also be possible to send a string representation of the assets KUID via the SetElementProperty mathod)
	<br><br>		<br><br>

---

Revision as of 17:39, 12 April 2019

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

Contents 1 Messages 2 Constants 3 General Methods 3.1 BringToFront 3.2 GetAsset 3.3 GetWindowVisible 3.4 LoadHTMLFile 3.5 LoadHTMLString 3.6 ResetScrollBar 3.7 SetCloseEnabled 3.8 SetParam 3.9 SetScrollEnabled 3.10 SetWindowStyle 3.11 SetWindowVisible 4 Browser Size & Position 4.1 GetWindowLeft 4.2 GetWindowTop 4.3 GetWindowRight 4.4 GetWindowBottom 4.5 GetWindowWidth 4.6 GetWindowHeight 4.7 SetWindowLeft 4.8 SetWindowTop 4.9 SetWindowRight 4.10 SetWindowBottom 4.11 SetWindowRect 4.12 SetWindowWidth 4.13 SetWindowHeight 4.14 SetWindowSize 4.15 SetWindowPosition 4.16 SetWindowGrow 5 Trainz Object HTML Element 5.1 GetElementProperty 5.2 SetElementObjectProperty 5.3 SetElementProperty 6 Trainz Text HTML Element 6.1 SetTrainzText 7 Code Examples 8 Related Methods 9 Categories

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

Parameters

• None

Returned Value

• None

Syntax

browser.BringToFront();

Notes

• Brings the window in front of all other browsers.

GetAsset

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

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

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

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

Parameters

• None

Returned Value

• None

Syntax

browser.ResetScrollBar();

Notes

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

SetCloseEnabled

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

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

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

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

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

• Retrieves the pixel coordinate of the left hand edge.

GetWindowTop

• Retrieves the pixel coordinate of the top edge.

GetWindowRight

• Retrieves the pixel coordinate of the right hand edge.

GetWindowBottom

• Retrieves the pixel coordinate of the bottom edge.

GetWindowWidth

• Retrieves the width of the window in pixels.

GetWindowHeight

• Retrieves the height of the window in pixels.

Parameters

• None

Syntax

int width = browser.GetWindowWidth();

Notes

SetWindowLeft

• Sets the pixel coordinate of the left hand edge.

SetWindowTop

• Sets the pixel coordinate of the top edge.

SetWindowRight

• Sets the pixel coordinate of the right hand edge.

SetWindowBottom

• Sets the pixel coordinate of the bottom edge.

SetWindowRect

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

SetWindowWidth

• Sets the width of the window in pixels.

SetWindowHeight

• Sets the height of the window in pixels.

SetWindowSize

• Sets the height and width of the window in pixels.

SetWindowPosition

• 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

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

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

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 (It might also be possible to send a string representation of the assets KUID via the SetElementProperty mathod)

SetElementProperty

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

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