Class Interface

Latest revision as of 23:45, 28 December 2020

API Hierarchy
- Interface

The Interface class provides scripts with methods to handle the user interface.

[edit] Constants & Messages

[edit] RGB Color Constants

Predefined 24 bit Red,Green,Blue color values
public define int Colour_Red = 0xFF0000	Red
public define int Colour_Green = 0x00FF00	Green
public define int Colour_Blue = 0x0000FF	Blue
public define int Colour_Yellow = 0xFFFF20	Yellow
public define int Colour_Cyan = 0xB0C0FF	Cyan
public define int Colour_White = 0xFFFFFF	White
public define int Colour_Black = 0x000000	Black

[edit] Button Element Indices

Constants referring to the buttons on the Driver menu
public define int ButtonBar_Element_Close = 0	Exit button
public define int ButtonBar_Element_Pause = 1	Pause button.
public define int ButtonBar_Element_Save = 2	Save button.
public define int ButtonBar_Element_Performance = 3	Performance Settings button.
public define int ButtonBar_Element_MetricImp = 4	Imperial/Metric button.
public define int ButtonBar_Element_Find = 5	Find button.
public define int ButtonBar_Element_Help = 6	On Screen Help button.

[edit] Related Messages

Messages sent to and from Industry objects are listed below:

Major	Minor	Source	Destination
Interface-Event	MapViewOff	?	Broadcast
Interface-Event	MapViewOn	?	Broadcast
Interface-Event	Mouse-Enter	MapObject	Broadcast
Interface-Event	Mouse-Leave	?	Broadcast
Interface-Event	Set-Metric-Mode	?	Broadcast
Interface-Event	Toggle-Interface	?	Broadcast

[edit] Methods

[edit] AdjustScore

public void AdjustScore(int delta)

Parameters

delta = Positive or negative increment to apply to score.

Returned Value

None

Syntax

AdjustScore(-5);

Notes

[edit] Exception

public native void Exception(string message)

Parameters

message = Message to be displayed and logged when the Exception occurs.

Returned Value

None

Syntax

Interface.Exception("Fatal Error");

Notes

Allows an exception to be explicitly raised by a script in the event of a major error condition.

[edit] GetDecoupleMode

public native bool GetDecoupleMode(void)

Parameters

None

Returned Value

Returns the current decoupling mode from the Driver interface.

Syntax

bool dcMode = Interface.GetDecoupleMode();

Notes

The decouple mode can be enabled or disabled when the user clicks on the decouple icon located on the Driver button bar or presses Ctrl + D.
When the interface is in decouple mode, the decouple icon will be highlighted.

[edit] GetDisplayHeight

public native int GetDisplayHeight(void)

Parameters

None

Returned Value

The height of the user's display in pixels.

Syntax

int height = Interface.GetDisplayHeight();

Notes

[edit] GetDisplayWidth

public native int GetDisplayWidth(void)

Parameters

None

Returned Value

The width of the user's display in pixels.

Syntax

int width = Interface.GetDisplayWidth();

Notes

[edit] GetElementProperty

public native string GetElementProperty(string elementId, string propertyId)

Parameters

elementId = Element to query.
propertyId = Property to query.

Returned Value

The value of the specified property if it exists, null otherwise.

Syntax

Notes

This method is used to read element properties of browser windows in the Trainz interface such as the Minimap.
See also SetElementProperty()

[edit] GetInterfaceVisible

public native bool GetInterfaceVisible(void)

Parameters

None

Returned Value

True if the Driver interface is visible, false otherwise.

Syntax

bool visible = Interface.GetInterfaceVisible();

Notes

The entire Driver mode interface can be hidden from view with the F5 key.

[edit] GetMapView

public native bool GetMapView(void)

Parameters

None

Returned Value

True if the map view window is visible, false otherwise.

Syntax

bool visible = Interface.GetMapView();

Notes

The minimap can be displayed or hidden by pressing M or Control + M;

[edit] GetMessageWindowVisible

public native bool GetMessageWindowVisible(void)

Parameters

None

Returned Value

True if the message window at the top of the screen is visible, false otherwise.

Syntax

bool visible = Interface.GetMessageWindowVisible();

Notes

[edit] GetMetricMode

public native bool GetMetricMode(void)

Parameters

None

Returned Value

True if the interface is displaying metric units, false for imperial.

Syntax

bool imperial = !Interface.GetMetricMode();

Notes

[edit] GetObjectiveBarVisible

public native bool GetObjectiveBarVisible()

Parameters

None

Returned Value

True if the Driver objective panel is visible, false otherwise.

Syntax

bool objectivesShown = Interface.GetObjectiveBarVisible();

Notes

The objective bar visibility can be toggled with the F6 key.

[edit] GetScore

public int GetScore(void)

Parameters

None

Returned Value

The current score.

Syntax

int score = GetScore();

Notes

[edit] GetTimeStamp

public native string GetTimeStamp(void)

Parameters

None

Returned Value

A real time timestamp in seconds.

Syntax

string timestamp = Interface.GetTimeStamp();

Notes

Returns the current time expressed as seconds elapsed since midnight on January 1, 1970 UTC.
The return value is a string as Trainzscript does not support any extended integer types.

[edit] GetWaybillWindowVisible

public bool GetWaybillWindowVisible()

Parameters

None

Returned Value

True if the Waybill Window is displayed, false otherwise.

Syntax

bool waybillVisible = GetWaybillWindowVisible();

Notes

[edit] HasUnseenMessages

public native bool HasUnseenMessages(void)

Parameters

None

Returned Value

True if there are messages intended for the Driver message window which have not been displayed, false otherwise.

Syntax

if (Interface.HasUnseenMessages()) Interface.SetMessageWindowVisible(true);

Notes

There are unseen messages if the message window is invisible yet messages have been received.
This is indicated to the user by the highlighted microphone icon on the Driver button bar.

[edit] HighlightButtonBarElement

public native void HighlightButtonBarElement(int buttonIndex, bool state)

Parameters

buttonIndex = One of the Button Element Index values defining the button to highlight.
state = True to turn highlighting on, false to turn it off.

Returned Value

None

Syntax

Interface.HighlightButtonBarElement(ButtonBar_Element_Pause,true);

Notes

Turns highlighting for a button on the Driver Menu either on or off.
This method allows a button on the Driver Menu found in the top left corner of the screen to be highlighted as if the mouse cursor was hovering above that button.
Note that the Driver Menu is not always visible, but you can explicitly show it with ShowDriverButtonMenu()

[edit] Log

public native void Log(string message)

Parameters

message = Text string to print to log file.

Returned Value

None

Syntax

Interface.Log("Session ended");

Notes

Prints a string of text to the jetlog.txt log file.
See also Print().
Disabled by default in TS12. See CCG/Modelling: TrainzOptions File.

[edit] LogCallStack

public native void LogCallStack(string message)

Parameters

message = Text string to be included with the call stack and printed to the log file.

Returned Value

None

Syntax

Interface.LogCallStack("Call Stack Contents");

Notes

[edit] LogResult

public void LogResult(string message)

Parameters

message = Text string to be included with the result and printed to the result log.

Returned Value

None

Syntax

Interface.LogResult("Result Appended");

Notes

[edit] Print

Print()

Parameters

message = Text string to print to log file and to the message window.

Returned Value

None

Syntax

Interface.Print("Session ended");

Notes

Prints a string of text to the jetlog.txt log file and echoes it to the messag window.
See also Log().

[edit] ResetResults

public void ResetResults()

Parameters

None

Returned Value

None

Syntax

Interface.ResetResults();

Notes

Clears the result log.

[edit] SetAlert

public native void SetAlert(string message, string iconTexture, float duration, int colour)

Parameters

message = Text of message to display.
iconTexture = Icon for alert, use an empty string for no icon.
duration = Time in seconds to keep the alert displayed.
colour = Color of alert text as a 24 bit RGB or as one of the RGB Color Constants.

Returned Value

None

Syntax

Interface.SetAlert("Train Halted due to leaves on line","",10.0,Interface.Colour_Red);

Notes: do not use in "Trainz 2019".

[edit] SetDecoupleMode

public native void SetDecoupleMode(bool enabled)

Parameters

enabled = Use true to enable decoupling, false to prevent.

Returned Value

None

Syntax

Interface.SetDecoupleMode(false);

Notes

The driver interface decoupling mode can be enabled or disabled using the icon on the Driver button bar or by keypress Ctrl + D.
When the interface is in decouple mode, the decouple icon will be highlighted.

[edit] SetElementProperty

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

Parameters

elementId = Element to update.
propertyId = Property to update.
value = New value to set.

Returned Value

None

Syntax

Interface.SetElementProperty(elementId,propertyId,value);

Notes

This method is used to modify element properties of browser windows in the Trainz interface such as the Minimap
See also GetElementProperty()

[edit] SetHelperIconScale

public native void SetHelperIconScale(float scale)

Parameters

scale = Scale factor to apply to on screen junction icons etc, range 0.5..1.0

Returned Value

None

Syntax

Interface.SetHelperIconScale(0.5); // set to 50% of default size

Notes

[edit] SetMapView

public native void SetMapView(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.SetMapView(true);

Notes

The user can show or hide the map view window by pressing M or Ctrl + M on the keyboard

[edit] SetMessageWindowVisible

public native void SetMessageWindowVisible(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

if (Interface.HasUnseenMessages()) Interface.SetMessageWindowVisible(true);

Notes

See Also GetMessageWindowVisible() and HasUnseenMessages().

[edit] SetMetricMode

public native mode SetMetricMode(bool useMetric)

Parameters

useMetric = Use true to select metric units, false to select imperial.

Returned Value

None

Syntax

Interface.SetMetricMode(false);

Notes

- See also GetMetricMode().

[edit] SetObjective

public native void SetObjective(string message, string iconTexture)

Parameters

message = Text for objective message.
iconTexture = Icon to display, use an empty string to omit the icon.

Returned Value

None

Syntax

Interface.SetObjective("Line closed ahead","");

Notes

This method will cause the driver objective panel to become visible.
The User can hide or show the panel at their discretion.

[edit] SetObjectiveBarVisible

public native void SetObjectiveBarVisible(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.SetObjectiveBarVisible(false);

Notes

The Driver objective bar can be toggled between invisible and visible by pressing the F6 key.

[edit] SetObjectiveIcon

public native void SetObjectiveIcon(string iconTexture)

Parameters

iconTexture = Icon to display, use an empty string to remove a previous icon.

Returned Value

None

Syntax

Interface.SetObjectiveIcon("");

Notes

The image file to use as the icon must be a 32x32 *.tga image.

[edit] SetResults

public native void SetResults(string message)

Parameters

message = String to display in results box.

Returned Value

None

Syntax

Interface.SetResults("Result text to display");

Notes

Displays the results of a scenario.
This method will change the activities menu to the results screen and fill out the results box with the given string.
The results will be visible when the user closes the activity module.

[edit] SetScore

public native void SetScore(string message)

Parameters

message = Message to display in the activity bar.

Returned Value

None

Syntax

Interface.SetScore("Score");

Notes

[edit] SetTooltip

public native void SetTooltip(Browser tooltip)

Parameters

tooltip = Browser to use as a tooltip window, if null the current tooltip will be removed.

Returned Value

None

Syntax

Interface.SetTooltip(tooltip);

Notes

Sets the tooltip that should follow the mouse around.
This method specifies that tooltip should follow the mouse.
Any existing tooltip will be replaced.
If this Browser is released, it will be removed automatically.

[edit] SetWaybillWindowVisible

public void SetWaybillWindowVisible(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.SetWaybillWindowVisible(false);

Notes

[edit] ShowDriverButtonMenu

public native void ShowDriverButtonMenu(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.ShowDriverButtonMenu(true);

Notes

Showing and hiding is not immediate, there may be a delay before it slides on or off.

[edit] ShowObjective

public native void ShowObjective(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.ShowObjective(true);

Notes

[edit] ShowOnScreenHelp

public native void ShowOnScreenHelp(bool visible)

Parameters

visible = Use true to display and false to hide.

Returned Value

None

Syntax

Interface.ShowOnScreenHelp(true);

Notes

This method performs the same function as the Show On-screen Help menu item in Driver which is used to display or hide names on map objects such as junctions.

[edit] WarnObsolete

public native void WarnObsolete(string warning)

Parameters

warning = Message to log to jetlog.txt at the first time this method is called.

Returned Value

None

Syntax

Interface.WarnObsolete("Method is obsolete");

Notes

Generates a runtime warning that a given function or usage is obsolete.
The warning goes to the JetLog.txt file and is not visible to the casual user within Trainz.
Only one warning is generated for any given warning string.

[edit] Code Examples

[edit] Related Methods

[edit] Categories

@@ Line 1: / Line 1: @@
-*[[TrainzScript Langage Reference|API Hierarchy]]
+*[[TrainzScript Library Reference|API Hierarchy]]
 **Interface
 <br>
@@ Line 11: / Line 11: @@
 <br>
 {{TableHeader|width=55%|margin=15px}}
-|bgcolor=#EEEEEE|'''Predefined 24 bit Red,Green,Blue colour values'''||bgcolor=#EEEEEE|
+|bgcolor=#EEEEEE|'''Predefined 24 bit Red,Green,Blue color values'''||bgcolor=#EEEEEE|
 |-
 |width=375|public define int  Colour_Red = 0xFF0000||width=225|Red
@@ Line 277: / Line 277: @@
 *Prints a string of text to the ''jetlog.txt'' log file.
 *See also [[#Print|Print()]].
+*Disabled by default in TS12. See [[CCG/Modelling: TrainzOptions File]].
 <br>
@@ Line 332: / Line 333: @@
 *'''iconTexture''' = Icon for alert, use an empty string for no icon.
 *'''duration''' = Time in seconds to keep the alert displayed.
-*'''colour''' = Colour of alert text as a 24 bit RGB or as one of the [[#RGB Colour Constants|RGB Colour Constants]].
+*'''colour''' = Color of alert text as a 24 bit RGB or as one of the [[#RGB Color Constants|RGB Color Constants]].
 ;Returned Value
 *None
 ;Syntax
   Interface.SetAlert("Train Halted due to leaves on line","",10.0,Interface.Colour_Red);
-;Notes
+;Notes: do not use in "Trainz 2019".
 <br>